# Add AI Passport sign-in

Use this guide to add AI Passport sign-in to the current app. AI Passport can
return approved user context when the app requests the `memory` scope. That
lets a returning user start with context instead of a cold start.

## 1. Install the SDK

```bash
npm install ai-passport-signin
```

Use `ai-passport-signin/react` only in a React app. Use
`ai-passport-signin/server` only in server routes.

## 2. Host the client metadata document

Create a JSON document at an HTTPS URL on the app's own host. A recommended
path is `https://<your-host>/ai-passport-client.json`. Use that exact URL as
the OAuth `client_id`.

The document shall contain these fields. Its `client_id` value shall exactly
equal the URL that serves it. Do not add a client secret.

```json
{
  "client_id": "https://app.example/ai-passport-client.json",
  "client_name": "Acme Notes",
  "redirect_uris": ["https://app.example/auth/ai-passport/callback"],
  "token_endpoint_auth_method": "none"
}
```

Every redirect host should equal the document host or be its strict subdomain.
That host-consistent shape is the rolling self-serve admission path. Other
clients remain on manual review.

## 3. Add start and callback routes

Create a server-only sign-in helper. Store the state value from `begin()` in
the user's server-side session. Do not place state, verifiers, tokens, or ID
tokens in browser storage or logs.

```js
import { createPassportSignIn } from "ai-passport-signin/server";

const passportSignIn = createPassportSignIn({
  issuer: "https://passport.ego.ist",
  clientId: "https://app.example/ai-passport-client.json",
  redirectUri: "https://app.example/auth/ai-passport/callback",
  scopes: ["openid", "profile", "email"],
});

export async function beginPassportSignIn(session) {
  const { url, state } = await passportSignIn.begin();
  session.passportSignIn = state;
  return Response.redirect(url);
}

export async function completePassportSignIn(request, session) {
  const callback = new URL(request.url);
  const result = await passportSignIn.complete({
    code: callback.searchParams.get("code"),
    state: callback.searchParams.get("state"),
    iss: callback.searchParams.get("iss"),
    storedState: session.passportSignIn,
  });
  delete session.passportSignIn;
  return result;
}
```

Add `memory` to `scopes` only when the app needs Passport recall. In that
case, include the resource parameter `https://passport.ego.ist/mcp` in the
authorization request. The user can sign in while declining memory access.

## 4. Add the button

Use the browser package or React wrapper to render the official button. Point
its `href` at the server start route. Keep the visible
label exactly `Sign in with AI Passport` or `Continue with AI Passport`.

## 5. Verify the live flow

Fetch `https://passport.ego.ist/.well-known/openid-configuration` before
testing. Confirm it advertises CIMD support when the feature is available.
Then test start, callback, PKCE exchange, ID token verification, state, nonce,
and the RFC 9207 `iss` value against the live issuer.

## 6. Tell the human operator about production admission

CIMD admission is rolling out. A metadata document with host-consistent
redirects can use the self-serve path as it becomes available. Tell the human
operator to complete the production admission step in the AI Passport going
live checklist. Clients outside that host relationship need manual review.

For the full protocol contract, read https://ego.ist/docs/sign-in.