@9in-io/sdk 0.0.0-stage → 0.1.1

package/dist/server.d.ts

@@ -0,0 +1,375 @@
+export { NineError, normalizeIssuer } from "./util.js";
+export interface VerifyOptions {
+    /** Your tenant's issuer (exactly as in the token's iss claim). */
+    issuer: string;
+    /** API identifier the token must be issued for (aud). */
+    audience?: string | string[];
+    /** Scopes that must all be present (space-separated or array). */
+    scope?: string | string[];
+    /**
+     * Shared secret of the HMAC key (HS256/384/512) your API signs with, from the console's
+     * key library. Only needed when the API uses an HMAC key; JWKS keys need nothing.
+     */
+    secret?: string;
+    /** Allowed clock skew in seconds (default 30). */
+    clockTolerance?: number;
+    /** Accept a plain-http issuer other than localhost (development only). */
+    allowInsecureIssuer?: boolean;
+    fetch?: typeof fetch;
+}
+export interface AccessTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    client_id: string;
+    scope: string;
+    jti?: string;
+    sid?: string;
+    auth_time?: number;
+    [claim: string]: unknown;
+}
+/**
+ * Verifies a 9in JWT access token locally: signature (against your tenant's JWKS, or your
+ * API's shared secret for HMAC keys), token type, issuer, audience, expiry and required
+ * scopes. Keys are cached and refetched once when a new key appears.
+ *
+ * This is a local check: a token revoked before it expires still passes. Use
+ * `createTokenVerifier` (hybrid mode) when revocation must take effect at once.
+ */
+export declare function verifyAccessToken(token: string | null | undefined, options: VerifyOptions): Promise<AccessTokenClaims>;
+export type VerificationMode = "local" | "hybrid" | "introspect";
+export interface TokenVerifierOptions extends Omit<VerifyOptions, "scope"> {
+    /**
+     * - `hybrid` (default): the local check, then one introspection per token; the answer is
+     *   cached and dropped when a `token.revoked`, `session.revoked` or user webhook arrives
+     *   (pass events to `handleEvent`), or after `cacheTtl` at the latest.
+     * - `local`: signature and claims only. Fastest; a revoked token works until it expires.
+     * - `introspect`: ask 9in on every call. Always current; one request per call.
+     * Opaque tokens (`9in_at_…`) are always introspected (and cached in hybrid mode).
+     */
+    mode?: VerificationMode;
+    /** A confidential application's credentials, used for introspection. */
+    clientId?: string;
+    clientSecret?: string;
+    /** Longest time a hybrid answer is trusted without hearing from 9in, in seconds (default 300). */
+    cacheTtl?: number;
+    /** Most tokens kept in the cache (default 10 000; the least recently used go first). */
+    cacheSize?: number;
+}
+export interface TokenVerifier {
+    /** Verifies a bearer token (JWT or opaque) and returns its claims, or throws `NineError`. */
+    verify(token: string | null | undefined, options?: {
+        scope?: string | string[];
+    }): Promise<AccessTokenClaims>;
+    /**
+     * Drops cached answers a webhook event makes stale; returns how many. Pass events from
+     * `verifyWebhook` (subscribe the endpoint to token.revoked, session.revoked,
+     * user.sessions_revoked, user.updated and user.deleted).
+     */
+    handleEvent(event: {
+        type: string;
+        data: Record<string, unknown>;
+    }): number;
+    /** Forgets every cached answer. */
+    clear(): void;
+}
+/**
+ * Token verification with a choice of trade-off between speed and revocation (SSOfy's
+ * "hybrid" validation, kept): see `mode`.
+ *
+ *   const verifier = createTokenVerifier({ issuer, audience: "https://api.acme.com", clientId, clientSecret });
+ *   const claims = await verifier.verify(bearer, { scope: "orders:read" });
+ *
+ *   // webhook endpoint (token.revoked, session.revoked, user.* events)
+ *   verifier.handleEvent(await verifyWebhook(secret, request));
+ */
+export declare function createTokenVerifier(options: TokenVerifierOptions): TokenVerifier;
+export interface ManagementOptions {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** Accept a plain-http issuer other than localhost (development only). */
+    allowInsecureIssuer?: boolean;
+    fetch?: typeof fetch;
+}
+export interface ManagedUser {
+    id: string;
+    email: string | null;
+    email_verified: boolean;
+    phone_number: string | null;
+    username: string | null;
+    name: string | null;
+    picture: string | null;
+    blocked: boolean;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    lastLoginAt: number | null;
+    [field: string]: unknown;
+}
+/** An active sign-in session (`sid` is the `sid` claim of its tokens). Times are ms since epoch. */
+export interface ManagedSession {
+    sid: string;
+    userId: string;
+    authTime: number;
+    amr: string[];
+    ip: string;
+    userAgent: string;
+    createdAt: number;
+    lastSeenAt: number;
+    expiresAt: number;
+    revokedAt: number | null;
+}
+/** One record for `importUsers`: the fields of `createUser` plus what an import may carry over. */
+export interface ImportUser {
+    /** Keep the id from your old system (letters, digits and | _ . : @ + -, max 128). */
+    id?: string;
+    email?: string | null;
+    emailVerified?: boolean;
+    /** E.164, e.g. +447700900000. */
+    phone?: string | null;
+    phoneVerified?: boolean;
+    username?: string | null;
+    name?: string | null;
+    given_name?: string | null;
+    family_name?: string | null;
+    picture?: string | null;
+    locale?: string | null;
+    zoneinfo?: string | null;
+    birthdate?: string | null;
+    metadata?: Record<string, unknown>;
+    blocked?: boolean;
+    /** A plain password (at most 50 such records per call), or `passwordHash` from your old system. */
+    password?: string;
+    /** bcrypt, argon2, PBKDF2 or Firebase scrypt hash: users keep their password. */
+    passwordHash?: string;
+    /** Linked sign-ins, e.g. { connection: "social:google", subject: "1069…" }. */
+    identities?: {
+        connection: string;
+        subject: string;
+    }[];
+    /** ms since epoch */
+    createdAt?: number;
+    lastLoginAt?: number;
+}
+/** Fields of a new user (`createUser`, `updateUser`). */
+export type NewUser = Omit<ImportUser, "id" | "identities" | "createdAt" | "lastLoginAt">;
+export type ImportResult = {
+    index: number;
+    ok: boolean;
+} & ({
+    status: "created" | "updated";
+    id: string;
+} | {
+    status: "skipped";
+    id: string;
+    reason: string;
+} | {
+    status: "failed";
+    error: string;
+    details?: unknown;
+});
+export declare class ManagementClient {
+    private readonly options;
+    /** One token per scope: each call asks only for what it needs, so an app granted some scopes works. */
+    private readonly tokens;
+    private readonly fetcher;
+    private readonly issuer;
+    constructor(options: ManagementOptions);
+    private accessToken;
+    private request;
+    listUsers(options?: {
+        query?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        users: ManagedUser[];
+        nextCursor: string | null;
+    }>;
+    getUser(id: string): Promise<{
+        user: ManagedUser;
+    }>;
+    findUserByEmail(email: string): Promise<{
+        user: ManagedUser;
+    }>;
+    /** Looks a user up by email, phone (E.164) or username; throws `not_found` (404) when unknown. */
+    findUser(type: "email" | "phone" | "username", value: string): Promise<{
+        user: ManagedUser;
+    }>;
+    createUser(input: NewUser): Promise<{
+        user: ManagedUser;
+    }>;
+    /**
+     * Bulk import, up to 500 users per call. Records may keep their old id and carry password
+     * hashes (bcrypt, argon2, PBKDF2, Firebase scrypt), social identities and original dates.
+     * Results are per record, in order; one bad record does not stop the others.
+     */
+    importUsers(users: ImportUser[], options?: {
+        onConflict?: "skip" | "update";
+        source?: string;
+    }): Promise<{
+        results: ImportResult[];
+    }>;
+    updateUser(id: string, input: Record<string, unknown>): Promise<{
+        user: ManagedUser;
+    }>;
+    deleteUser(id: string): Promise<void>;
+    blockUser(id: string, blocked?: boolean): Promise<{
+        user: ManagedUser;
+    }>;
+    /**
+     * Single-use URL that signs the user in (magic links, handing a user over from your app).
+     * `returnTo` must be a registered redirect URL of one of your applications or a path on
+     * the login domain. Two-factor authentication still applies.
+     */
+    createLoginLink(id: string, options?: {
+        returnTo?: string;
+        ttlSeconds?: number;
+    }): Promise<{
+        url: string;
+        expires_at: number;
+    }>;
+    /** The user's active sessions, most recently used first. */
+    listUserSessions(id: string): Promise<{
+        sessions: ManagedSession[];
+    }>;
+    /** Signs the user out everywhere; returns how many sessions ended. */
+    revokeUserSessions(id: string): Promise<{
+        revoked: number;
+    }>;
+    /** Ends one session (its `sid`) and every token issued under it. */
+    revokeSession(sid: string): Promise<void>;
+}
+export interface AdapterIdentifier {
+    type: "email" | "username" | "phone";
+    value: string;
+}
+export interface AdapterUser {
+    id: string;
+    email?: string | null;
+    email_verified?: boolean | null;
+    phone_number?: string | null;
+    phone_number_verified?: boolean | null;
+    username?: string | null;
+    name?: string | null;
+    given_name?: string | null;
+    family_name?: string | null;
+    picture?: string | null;
+    locale?: string | null;
+    zoneinfo?: string | null;
+    birthdate?: string | null;
+    blocked?: boolean | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AdapterEvent {
+    id: string;
+    type: "otp.requested" | "user.created" | "user.updated" | "user.password_changed" | "session.revoked";
+    createdAt: string;
+    data: Record<string, unknown>;
+}
+export interface AdapterHandlers {
+    /** Shared secret from the console (Connections → User database). Several allow rotation. */
+    secret: string | string[];
+    /** Check a password. Return the user, "invalid" or "blocked". */
+    authenticate(identifier: AdapterIdentifier, password: string): Promise<AdapterUser | "invalid" | "blocked">;
+    /** Look a user up by identifier or id; null when unknown. */
+    findUser(query: {
+        identifier: AdapterIdentifier;
+    } | {
+        id: string;
+    }): Promise<AdapterUser | null>;
+    /** Notifications, including `otp.requested` when you deliver codes yourself. */
+    onEvent?(event: AdapterEvent): Promise<void>;
+    /** Signature tolerance in seconds (default 300). */
+    toleranceSeconds?: number;
+}
+/** Verifies a `9in-signature` header: t=<unix>,v1=<hex HMAC(t.METHOD.path.body)>. */
+export declare function verifySignature(secret: string | string[], header: string | null, method: string, path: string, body: string, toleranceSeconds?: number): Promise<boolean>;
+export declare function signPayload(secret: string, method: string, path: string, body: string): Promise<string>;
+export type WebhookEventType = "user.created" | "user.updated" | "user.deleted" | "user.login" | "user.login_failed" | "user.password_changed" | "user.mfa_enabled" | "user.mfa_disabled" | "user.sessions_revoked" | "session.revoked" | "token.revoked" | "webhook.test";
+export interface WebhookEvent<Data extends Record<string, unknown> = Record<string, unknown>> {
+    /** Event id: the same on every retry and redelivery, so you can ignore duplicates. */
+    id: string;
+    type: WebhookEventType;
+    createdAt: string;
+    /** Tenant id (tnt_…). */
+    tenant: string;
+    environment: "production" | "sandbox";
+    /** Event details, plus `userId` and a `user` snapshot (null once deleted) for user events. */
+    data: Data & {
+        userId?: string | null;
+        user?: ManagedUser | null;
+    };
+}
+export interface VerifyWebhookOptions {
+    /** Signature tolerance in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** The path 9in posted to, when a proxy or framework rewrote `request.url` (default: its pathname). */
+    path?: string;
+}
+/**
+ * Verifies a webhook request from 9in (the `9in-signature` header over the raw body) and
+ * returns the parsed event. Throws `NineError` (`invalid_signature`, 401) otherwise. Reads
+ * the body, so pass `request.clone()` if you need it afterwards.
+ *
+ *   const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
+ *   if (event.type === "user.created") …
+ */
+export declare function verifyWebhook(secret: string | string[], request: Request, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
+/**
+ * Key-value store for `processEventOnce`. `add` must be atomic (insert only when the key is
+ * absent or expired): use a Durable Object, D1/SQL with a unique key, or Redis `SET NX EX`.
+ * Workers KV is eventually consistent and not suitable.
+ */
+export interface EventStore {
+    add(key: string, value: string, ttlSeconds: number): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** In-memory EventStore: one process only (tests, single-instance servers). */
+export declare class MemoryEventStore implements EventStore {
+    private readonly items;
+    private live;
+    add(key: string, value: string, ttlSeconds: number): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface ProcessOnceOptions {
+    /** How long a processed id is remembered (default 3 days; 9in retries for about a day). */
+    ttlSeconds?: number;
+    /** How long a running handler holds the id before another delivery may take over (default 300). */
+    lockSeconds?: number;
+    /** Key prefix (default "9in:event:"). */
+    prefix?: string;
+}
+export type ProcessOnceResult<T> = {
+    status: "processed";
+    result: T;
+} | {
+    status: "duplicate";
+} | {
+    status: "in_progress";
+};
+/**
+ * Runs `handler` at most once per event id. 9in keeps the id on every retry and redelivery.
+ *
+ * - `processed`: first delivery, handler succeeded → answer 2xx.
+ * - `duplicate`: already processed → answer 2xx so 9in stops retrying.
+ * - `in_progress`: another delivery of the same event is still running → answer 409 so
+ *   9in tries again later.
+ * - The handler threw: the id is released and the error rethrown → answer 5xx so 9in retries.
+ *
+ *   const event = await verifyWebhook(secret, request);
+ *   const outcome = await processEventOnce(store, event.id, () => handle(event));
+ *   return new Response(null, { status: outcome.status === "in_progress" ? 409 : 204 });
+ */
+export declare function processEventOnce<T>(store: EventStore, eventId: string, handler: () => T | Promise<T>, options?: ProcessOnceOptions): Promise<ProcessOnceResult<T>>;
+/**
+ * Fetch-API handler for the adapter protocol. Mount it at your adapter base URL (it serves
+ * `…/authenticate`, `…/user` and `…/event`) in Cloudflare Workers, Deno, Bun, Hono, or Node
+ * with any Request/Response bridge (Express: `@whatwg-node/server`, Next.js route handlers…).
+ */
+export declare function adapterHandler(handlers: AdapterHandlers): (request: Request) => Promise<Response>;