Install with AI

Choose what you're adding. Paste the prompt into Claude Code, Cursor or any coding agent, or give it the link. Prompts never contain secrets.
Services

Sign in with OnusHosted sign-in, callback, sessions and sign-outProtect an API with Onus access tokensVerify Onus access tokens on your API routesCall the Onnisoft Hub APIRead your organisation, products and newsReceive Onnisoft Hub webhooksA verified endpoint for Hub events
Your app

Framework
App URL
Onus

Find these in the console
Prompt

Or tell your agent: Read this and follow it.
https://docs.onnisoft.site/install/prompt.md?services=onus-signin
# Add Onnisoft to this project

You're adding sign-in with Onus to this codebase. Work through the sections in order, keep changes small and in the project's existing style, and ask me before adding a dependency other than the ones named here.

## Ground rules

- Never ask me to paste a secret into this conversation, and never write secret values into code, commits, logs, tests or fixtures. Read them from environment variables, and add only their names to `.env.example` (create it if missing).
- Never log tokens, authorization codes, API keys, webhook bodies or full callback URLs.
- Use the official SDK below for every check it performs (state, issuer, PKCE, token signatures, webhook signatures). Don't hand-roll JWT or HMAC verification.
- Don't build a login form, password field, passkey (WebAuthn) code or social buttons: Onus hosts the sign-in page.
- If something here conflicts with what you find in the code, stop and tell me instead of guessing.

## Facts already decided

- Onus issuer: `https://onus.onnisoft.site/t/<project>` (ask me for the project slug)
- Client ID: ask me (Onus console → Applications)
- Client type: confidential (server-side). The secret is read from `ONUS_CLIENT_SECRET` on the server only.
- Redirect URI: `<APP_URL>/auth/callback`. After sign-out: `<APP_URL>/`.
- Scopes: `openid email offline_access`.

## 1. Find the stack

Identify the framework, router, session mechanism and package manager from the repository before writing code, and tell me what you found in one line. Then apply the matching notes:

- **Next.js (App Router).** Route handlers in `app/auth/login/route.ts`, `app/auth/callback/route.ts` and `app/auth/logout/route.ts`; read and write cookies with `cookies()` from `next/headers`. The SDK uses Web Crypto, so the Node and Edge runtimes both work. `middleware.ts` may redirect when the session cookie is missing, but do the real session check in server components and route handlers.
- **Express.** Use the project's session library if it has one; otherwise `express-session` with a server-side store, or signed cookies via `cookie-parser` and `SESSION_SECRET`. Behind a proxy set `app.set("trust proxy", 1)` so Secure cookies work. Register `/auth/login`, `/auth/callback` and `/auth/logout`, plus a `requireUser` middleware.
- **Hono / Cloudflare Workers.** Use `setSignedCookie` / `getSignedCookie` from `hono/cookie` with `SESSION_SECRET`; keep sessions in KV or D1 if the project has either. Secrets come from `c.env` and are set with `wrangler secret put` (never in `wrangler.jsonc`); local values go in `.dev.vars`, which must be gitignored.
- **SvelteKit.** Endpoints in `src/routes/auth/login/+server.ts`, `…/callback/+server.ts` and `…/logout/+server.ts`; load the session in `hooks.server.ts` into `event.locals`; use `event.cookies` (httpOnly, secure, sameSite "lax"). Read secrets from `$env/static/private`.
- **Single-page app (public client).** There is no client secret and there must not be one in the bundle. Prefer adding a small backend (a "backend for frontend") and following the server flow; if the app must stay static: keep `state`, `nonce` and `codeVerifier` in `sessionStorage` only until the callback, keep tokens in memory (never `localStorage`), don't request `offline_access`, and send the user through `/authorize` again (it's instant while their Onus session lasts) when the access token expires.

## 2. Install the SDK

The SDK is `@onnisoft/sdk` (one dependency, `jose`). It isn't on the npm registry; install the published tarball with the project's package manager (npm, pnpm, yarn and bun all accept a URL):

```bash
npm install https://docs.onnisoft.site/sdk/onnisoft-sdk-0.1.0.tgz
```

Import from `@onnisoft/sdk/onus` and `@onnisoft/sdk/hub`. Keep the lockfile change.

## 3. Onus client

Create one module (for example `lib/onus.ts`) that exports a single client:

```ts
import { createOnusClient } from "@onnisoft/sdk/onus";

export const onus = createOnusClient({
  issuer: process.env.ONUS_ISSUER!, // https://onus.onnisoft.site/t/<project>
  clientId: process.env.ONUS_CLIENT_ID!,
  clientSecret: process.env.ONUS_CLIENT_SECRET, // server only
  redirectUri: `${process.env.APP_URL}/auth/callback`,
});
```

Adapt how configuration is read to the framework (for example `c.env` on Workers).

## 4. Sign-in, callback, sign-out

**`GET /auth/login`**: call `onus.authorizationUrl({ scope: "openid email offline_access" })`. Save `{ state, nonce, codeVerifier, returnTo }` in a short-lived cookie (httpOnly, Secure, `SameSite=Lax`, path `/auth`, 10 minutes, signed or encrypted with `SESSION_SECRET`) or in the server session, then redirect (302) to `url`. `returnTo` must be a same-origin path; ignore anything else. `SameSite=Lax` matters: `Strict` drops the cookie on the way back from Onus.

**`GET /auth/callback`**: read and delete that cookie, then `const { tokens, claims } = await onus.handleCallback(new URL(request.url), saved)`. On `OnusError` show a short message with a "Try again" link to `/auth/login`. On success create the app session with a fresh ID: store `claims.sub` (the stable user ID; never key users by email), `claims.email`, `claims.sid` and the tokens **server-side**. The refresh token must never reach the browser (no `localStorage`, no readable cookie). Redirect to `returnTo` or `/`.

**Refreshing**: before calling your API with an expired access token, call `onus.refresh(refreshToken)`. Refresh tokens rotate: save the new one immediately (atomically, so two parallel requests can't both use the old one). On `invalid_grant`, clear the session and send the user to `/auth/login`.

**`POST /auth/logout`** (POST with the project's CSRF protection, not GET): call `onus.revoke(refreshToken)`, destroy the app session, then redirect to `onus.logoutUrl(idToken, process.env.APP_URL + "/")` so the Onus session ends too.

**Protected pages**: add a helper or middleware that loads the session and redirects to `/auth/login?returnTo=…` when there isn't one. Show the signed-in email and a sign-out button somewhere sensible.

## 5. Environment

Add these to `.env.example` (names only for secrets) and wherever the project documents configuration:

| Variable | Value |
| --- | --- |
| `ONUS_ISSUER` | `https://onus.onnisoft.site/t/<project>` |
| `ONUS_CLIENT_ID` | `from the console` |
| `APP_URL` | `this app's origin, no trailing slash` |
| `ONUS_CLIENT_SECRET` | secret · shown once in the console |
| `SESSION_SECRET` | secret · 32+ random bytes, if the session library needs one |

## 6. Check your work

- Run the project's type checker, linter and tests, and fix what you broke.
- Add tests for: callback with a wrong `state` is rejected; `returnTo` pointing at another origin is ignored; protected pages redirect when signed out.
- Search your diff for anything that looks like a secret (`onus_sk_`, `onx_`, `whsec_`, `onus_rt_`, long base64) and remove it.
- Tell me how to try it locally.

## When you're done

Summarise what changed, file by file, then list these steps for me to do; don't attempt them yourself:

- In the Onus console → Applications → your application: add `<APP_URL>/auth/callback` as a redirect URI and `<APP_URL>/` under *After sign-out*.

## Reference

- Onus: https://docs.onnisoft.site/onus (OpenAPI: https://docs.onnisoft.site/openapi/onus.yaml)
- Everything for agents: https://docs.onnisoft.site/llms.txt