@nimbus-sh/worker 0.1.0

package/dist/auth/middleware.js

@@ -0,0 +1,150 @@
+/**
+ * auth/middleware.ts — Request-time extract + verify glue.
+ *
+ * `extractBearerToken(request)` pulls the token from one of three places,
+ * in order of precedence:
+ *   1. `Authorization: Bearer <token>` header (canonical).
+ *   2. `?nimbus_token=<token>` query parameter (for `<iframe src>`).
+ *   3. `nimbus_token=<token>` cookie (for browser nav after the iframe
+ *      sets it; the iframe can read its own cookie because cookies are
+ *      scoped to the Nimbus origin, not the embedder's).
+ *
+ * The query/cookie fallbacks exist because `<iframe>` URLs are the
+ * canonical embed shape for `<NimbusTerminal>` and browsers don't let
+ * cross-origin iframes carry custom request headers on the initial
+ * navigation request. The cookie path is used for post-load nav inside
+ * the iframe (e.g. browser back/forward).
+ *
+ * NOTE: when the request comes from inside an `<iframe src="...?nimbus_token=...">`,
+ * we set the cookie on the response so subsequent in-iframe navigations
+ * don't need to re-pass the query param. See `setNimbusTokenCookie`.
+ */
+import { verifyNimbusToken } from './token.js';
+import { NimbusAuthError, NimbusTokenMalformedError, NimbusScopeError, NimbusSessionPinError, } from './types.js';
+/** Cookie name used for in-iframe token persistence. */
+export const NIMBUS_TOKEN_COOKIE = 'nimbus_token';
+/** Query parameter name. */
+export const NIMBUS_TOKEN_QUERY = 'nimbus_token';
+/**
+ * Pull a token from a Request. Returns null if absent (caller decides
+ * whether absence is an auth failure or just "anonymous").
+ *
+ * Precedence: Authorization header → query → cookie.
+ */
+export function extractBearerToken(request) {
+    // 1. Authorization header.
+    const auth = request.headers.get('Authorization');
+    if (auth) {
+        const m = auth.match(/^Bearer\s+(.+)$/i);
+        if (m)
+            return m[1];
+    }
+    // 2. Query parameter.
+    const url = new URL(request.url);
+    const q = url.searchParams.get(NIMBUS_TOKEN_QUERY);
+    if (q && q.length > 0)
+        return q;
+    // 3. Cookie.
+    const cookie = request.headers.get('Cookie');
+    if (cookie) {
+        for (const c of cookie.split(';')) {
+            const [k, v] = c.trim().split('=', 2);
+            if (k === NIMBUS_TOKEN_COOKIE && v)
+                return decodeURIComponent(v);
+        }
+    }
+    return null;
+}
+/**
+ * Verify a token from a Request. Convenience wrapper around
+ * {@link extractBearerToken} + {@link verifyNimbusToken}.
+ *
+ * @throws {NimbusTokenMalformedError} when no token is present and
+ *         `requireToken` is true (default).
+ * @throws Any error from {@link verifyNimbusToken}.
+ */
+export async function verifyRequestToken(request, env, opts = {}) {
+    const token = extractBearerToken(request);
+    if (!token) {
+        if (opts.requireToken === false)
+            return null;
+        throw new NimbusTokenMalformedError('no Bearer token in Authorization header, nimbus_token query, or cookie');
+    }
+    return verifyNimbusToken(env, token);
+}
+/**
+ * Assert that the verified token carries every required scope.
+ *
+ * Tokens with `scopes === undefined` are treated as "all permitted"
+ * (legacy/full-trust). Tokens with an explicit `scopes` array must
+ * contain every entry in `required`.
+ *
+ * @throws {NimbusScopeError} on the first missing scope.
+ */
+export function requireScopes(verified, required) {
+    if (verified.claims.scopes === undefined)
+        return;
+    for (const r of required) {
+        if (!verified.claims.scopes.includes(r)) {
+            throw new NimbusScopeError(r);
+        }
+    }
+}
+/**
+ * Assert that a sid-pinned token matches the session being attached. No-op
+ * if the token isn't sid-pinned.
+ *
+ * @throws {NimbusSessionPinError} on mismatch.
+ */
+export function requireSessionPin(verified, attemptedSessionId) {
+    if (verified.claims.sid !== undefined && verified.claims.sid !== attemptedSessionId) {
+        throw new NimbusSessionPinError(verified.claims.sid, attemptedSessionId);
+    }
+}
+/**
+ * Build a Set-Cookie header value persisting the token in-iframe so
+ * subsequent navigations don't need the `?nimbus_token=` query.
+ *
+ * Cookie attributes:
+ *   - HttpOnly: NO — JS in the iframe shell needs to forward the token
+ *     to its WebSocket via subprotocol. Keep this in mind for XSS posture
+ *     (Nimbus's xterm shell never executes embedder JS, mitigating risk).
+ *   - Secure: YES (production).
+ *   - SameSite=None: required because the iframe is cross-origin from
+ *     the embedder's app. Pairs with Secure.
+ *   - Path: scoped to `/s/` so non-session paths don't see the cookie.
+ *   - Max-Age: matches the token's remaining lifetime.
+ */
+export function setNimbusTokenCookie(token, expSec, opts = {}) {
+    const secure = opts.secure !== false; // default true
+    const nowSec = Math.floor(Date.now() / 1000);
+    const maxAge = Math.max(0, expSec - nowSec);
+    const parts = [
+        `${NIMBUS_TOKEN_COOKIE}=${encodeURIComponent(token)}`,
+        'Path=/s',
+        `Max-Age=${maxAge}`,
+        'SameSite=None',
+    ];
+    if (secure)
+        parts.push('Secure');
+    return parts.join('; ');
+}
+/**
+ * Map a NimbusAuthError to a `Response` suitable for the embedder's
+ * `fetch` handler to return. JSON body with `{ error, code }`.
+ */
+export function authErrorResponse(e) {
+    if (e instanceof NimbusAuthError) {
+        return new Response(JSON.stringify({ error: e.message, code: e.code }), {
+            status: e.httpStatus,
+            headers: {
+                'Content-Type': 'application/json',
+                'Cache-Control': 'no-store',
+                // Hint to browsers that this is an auth challenge.
+                ...(e.httpStatus === 401 ? { 'WWW-Authenticate': 'Bearer realm="nimbus"' } : {}),
+            },
+        });
+    }
+    // Unknown error — don't leak the message; log on caller side.
+    return new Response(JSON.stringify({ error: 'Internal auth error', code: 'E_AUTH_UNKNOWN' }), { status: 500, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } });
+}

package/dist/auth/token.d.ts

@@ -0,0 +1,96 @@
+/**
+ * auth/token.ts — HS256 JWT issue + verify via WebCrypto subtle.
+ *
+ * Why HS256 (not RS256/ES256, not OAuth introspection)?
+ *   - Embedder and Nimbus share `JWT_SECRET` via `wrangler secret put`.
+ *     No external IDP needed; works on day-1 for any Workers project.
+ *   - HMAC is constant-time-comparable, supported natively by WebCrypto,
+ *     and zero-dependency.
+ *   - Pattern matches Mossaic exactly — port surface (`scope`, `tn`,
+ *     `sub?`, `sid?`, `iat`, `exp`) is identical except the `scope` value.
+ *
+ * Why WebCrypto over `jose`?
+ *   - One fewer dependency in the SDK package. `jose` is great but pulls
+ *     in ~70 KB of code for features we don't use (RSA, EC, JWE, JWK).
+ *   - `crypto.subtle.{importKey,sign,verify}` is available identically in
+ *     workerd, Node ≥ 18, and modern browsers. Test parity is excellent.
+ *
+ * Wire format:
+ *
+ *   <b64url(header)>.<b64url(payload)>.<b64url(hmacSha256(secret, ".".join(...)))>
+ *
+ * `header` is constant `{"alg":"HS256","typ":"JWT"}`. We never read alg
+ * from the header at verify-time (eliminates the `alg: "none"` confusion
+ * attack class — see RFC 8725 §3.1).
+ */
+import { type VerifiedNimbusToken, type IssueTokenOptions } from './types.js';
+/**
+ * The minimum env shape required by issue/verify. Embedders typically use
+ * `Env extends NimbusAuthEnv & ...other-bindings...` to compose.
+ */
+export interface NimbusAuthEnv {
+    /** HMAC secret. Set via `wrangler secret put JWT_SECRET`. */
+    JWT_SECRET: string;
+    /**
+     * Optional previous-generation secret for rotation. When set, verify
+     * accepts tokens signed by either. Issue always uses the primary.
+     */
+    JWT_SECRET_PREVIOUS?: string;
+}
+/**
+ * Mint a Nimbus JWT.
+ *
+ * @example Mint a 1-hour session token for a tenant user.
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * const token = await issueNimbusToken(env, { tn: 'acme', sub: 'alice' });
+ * ```
+ *
+ * @example Mint an admin token with `session:admin` scope, 24 hours.
+ * ```ts
+ * const token = await issueNimbusToken(
+ *   env,
+ *   { tn: 'acme', sub: 'ops', scopes: ['session:admin'] },
+ *   { ttlMs: 24 * 60 * 60 * 1000 },
+ * );
+ * ```
+ *
+ * @param env Object with at least `JWT_SECRET`.
+ * @param input Claims-without-iat/exp/scope. `scope` is set to `"nimbus"`
+ *              by this function; do not pass it in.
+ * @param opts Optional `ttlMs` (default {@link DEFAULT_TOKEN_TTL_MS}, max
+ *             {@link MAX_TOKEN_TTL_MS}) and `iatOverride` (tests only).
+ *
+ * @throws {NimbusAuthConfigError} when `env.JWT_SECRET` is missing/empty.
+ * @throws {NimbusTokenClaimsError} when `tn`/`sub` shape is invalid.
+ * @throws {NimbusTokenTtlError} when `opts.ttlMs` > {@link MAX_TOKEN_TTL_MS}.
+ */
+export declare function issueNimbusToken(env: NimbusAuthEnv, input: {
+    tn: string;
+    sub?: string;
+    scopes?: string[];
+    sid?: string;
+}, opts?: IssueTokenOptions): Promise<string>;
+/**
+ * Verify a Nimbus JWT and return the parsed claims + canonical DO name.
+ *
+ * @example Verify a token at request-time.
+ * ```ts
+ * import { verifyNimbusToken } from '@nimbus-sh/sdk/token';
+ * const { claims, doInstanceName } = await verifyNimbusToken(env, token);
+ * // → idFromName(`${doInstanceName}:${sessionId}`)
+ * ```
+ *
+ * @param env Object with `JWT_SECRET` and optional `JWT_SECRET_PREVIOUS`.
+ * @param token Raw JWT string (no `Bearer ` prefix — caller strips that).
+ *
+ * @throws {NimbusAuthConfigError} when `env.JWT_SECRET` is missing.
+ * @throws {NimbusTokenMalformedError} when token is not 3 b64 parts.
+ * @throws {NimbusTokenSignatureError} when HMAC verify fails for both
+ *         primary and previous secrets.
+ * @throws {NimbusTokenClaimsError} when payload fields are missing or
+ *         shape-invalid.
+ * @throws {NimbusTokenExpiredError} when `exp` < `now`.
+ */
+export declare function verifyNimbusToken(env: NimbusAuthEnv, token: string): Promise<VerifiedNimbusToken>;
+//# sourceMappingURL=token.d.ts.map

package/dist/auth/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/auth/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAWL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IACL,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,EACD,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,mBAAmB,CAAC,CAwE9B"}

package/dist/auth/token.js

@@ -0,0 +1,226 @@
+/**
+ * auth/token.ts — HS256 JWT issue + verify via WebCrypto subtle.
+ *
+ * Why HS256 (not RS256/ES256, not OAuth introspection)?
+ *   - Embedder and Nimbus share `JWT_SECRET` via `wrangler secret put`.
+ *     No external IDP needed; works on day-1 for any Workers project.
+ *   - HMAC is constant-time-comparable, supported natively by WebCrypto,
+ *     and zero-dependency.
+ *   - Pattern matches Mossaic exactly — port surface (`scope`, `tn`,
+ *     `sub?`, `sid?`, `iat`, `exp`) is identical except the `scope` value.
+ *
+ * Why WebCrypto over `jose`?
+ *   - One fewer dependency in the SDK package. `jose` is great but pulls
+ *     in ~70 KB of code for features we don't use (RSA, EC, JWE, JWK).
+ *   - `crypto.subtle.{importKey,sign,verify}` is available identically in
+ *     workerd, Node ≥ 18, and modern browsers. Test parity is excellent.
+ *
+ * Wire format:
+ *
+ *   <b64url(header)>.<b64url(payload)>.<b64url(hmacSha256(secret, ".".join(...)))>
+ *
+ * `header` is constant `{"alg":"HS256","typ":"JWT"}`. We never read alg
+ * from the header at verify-time (eliminates the `alg: "none"` confusion
+ * attack class — see RFC 8725 §3.1).
+ */
+import { DEFAULT_TOKEN_TTL_MS, MAX_TOKEN_TTL_MS, ID_COMPONENT_RE, NimbusAuthConfigError, NimbusTokenMalformedError, NimbusTokenSignatureError, NimbusTokenClaimsError, NimbusTokenExpiredError, NimbusTokenTtlError, } from './types.js';
+/** Constant JWT header. Serialized at module load; we just splice the cached b64. */
+const HEADER_JSON = '{"alg":"HS256","typ":"JWT"}';
+const HEADER_B64 = b64urlEncodeString(HEADER_JSON);
+/**
+ * Mint a Nimbus JWT.
+ *
+ * @example Mint a 1-hour session token for a tenant user.
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * const token = await issueNimbusToken(env, { tn: 'acme', sub: 'alice' });
+ * ```
+ *
+ * @example Mint an admin token with `session:admin` scope, 24 hours.
+ * ```ts
+ * const token = await issueNimbusToken(
+ *   env,
+ *   { tn: 'acme', sub: 'ops', scopes: ['session:admin'] },
+ *   { ttlMs: 24 * 60 * 60 * 1000 },
+ * );
+ * ```
+ *
+ * @param env Object with at least `JWT_SECRET`.
+ * @param input Claims-without-iat/exp/scope. `scope` is set to `"nimbus"`
+ *              by this function; do not pass it in.
+ * @param opts Optional `ttlMs` (default {@link DEFAULT_TOKEN_TTL_MS}, max
+ *             {@link MAX_TOKEN_TTL_MS}) and `iatOverride` (tests only).
+ *
+ * @throws {NimbusAuthConfigError} when `env.JWT_SECRET` is missing/empty.
+ * @throws {NimbusTokenClaimsError} when `tn`/`sub` shape is invalid.
+ * @throws {NimbusTokenTtlError} when `opts.ttlMs` > {@link MAX_TOKEN_TTL_MS}.
+ */
+export async function issueNimbusToken(env, input, opts = {}) {
+    if (!env || typeof env.JWT_SECRET !== 'string' || env.JWT_SECRET.length === 0) {
+        throw new NimbusAuthConfigError('JWT_SECRET is not configured (set via `wrangler secret put JWT_SECRET`)');
+    }
+    if (!ID_COMPONENT_RE.test(input.tn)) {
+        throw new NimbusTokenClaimsError(`tn must match ${ID_COMPONENT_RE} (got: ${JSON.stringify(input.tn)})`);
+    }
+    if (input.sub !== undefined && !ID_COMPONENT_RE.test(input.sub)) {
+        throw new NimbusTokenClaimsError(`sub must match ${ID_COMPONENT_RE} (got: ${JSON.stringify(input.sub)})`);
+    }
+    if (input.sid !== undefined && !ID_COMPONENT_RE.test(input.sid)) {
+        throw new NimbusTokenClaimsError(`sid must match ${ID_COMPONENT_RE} (got: ${JSON.stringify(input.sid)})`);
+    }
+    const ttlMs = opts.ttlMs ?? DEFAULT_TOKEN_TTL_MS;
+    if (ttlMs <= 0) {
+        throw new NimbusTokenTtlError(ttlMs, MAX_TOKEN_TTL_MS);
+    }
+    if (ttlMs > MAX_TOKEN_TTL_MS) {
+        throw new NimbusTokenTtlError(ttlMs, MAX_TOKEN_TTL_MS);
+    }
+    const iat = opts.iatOverride ?? Math.floor(Date.now() / 1000);
+    const exp = iat + Math.floor(ttlMs / 1000);
+    const claims = {
+        scope: 'nimbus',
+        tn: input.tn,
+        ...(input.sub !== undefined && { sub: input.sub }),
+        ...(input.scopes !== undefined && { scopes: input.scopes }),
+        ...(input.sid !== undefined && { sid: input.sid }),
+        iat,
+        exp,
+    };
+    const payloadB64 = b64urlEncodeString(JSON.stringify(claims));
+    const signingInput = `${HEADER_B64}.${payloadB64}`;
+    const sig = await hmacSha256(env.JWT_SECRET, signingInput);
+    return `${signingInput}.${b64urlEncodeBytes(sig)}`;
+}
+/**
+ * Verify a Nimbus JWT and return the parsed claims + canonical DO name.
+ *
+ * @example Verify a token at request-time.
+ * ```ts
+ * import { verifyNimbusToken } from '@nimbus-sh/sdk/token';
+ * const { claims, doInstanceName } = await verifyNimbusToken(env, token);
+ * // → idFromName(`${doInstanceName}:${sessionId}`)
+ * ```
+ *
+ * @param env Object with `JWT_SECRET` and optional `JWT_SECRET_PREVIOUS`.
+ * @param token Raw JWT string (no `Bearer ` prefix — caller strips that).
+ *
+ * @throws {NimbusAuthConfigError} when `env.JWT_SECRET` is missing.
+ * @throws {NimbusTokenMalformedError} when token is not 3 b64 parts.
+ * @throws {NimbusTokenSignatureError} when HMAC verify fails for both
+ *         primary and previous secrets.
+ * @throws {NimbusTokenClaimsError} when payload fields are missing or
+ *         shape-invalid.
+ * @throws {NimbusTokenExpiredError} when `exp` < `now`.
+ */
+export async function verifyNimbusToken(env, token) {
+    if (!env || typeof env.JWT_SECRET !== 'string' || env.JWT_SECRET.length === 0) {
+        throw new NimbusAuthConfigError('JWT_SECRET is not configured (set via `wrangler secret put JWT_SECRET`)');
+    }
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new NimbusTokenMalformedError('token must be a non-empty string');
+    }
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        throw new NimbusTokenMalformedError(`expected 3 dot-separated parts, got ${parts.length}`);
+    }
+    const [headerB64, payloadB64, sigB64] = parts;
+    const signingInput = `${headerB64}.${payloadB64}`;
+    // Verify against primary, then previous (for rotation windows).
+    const sigBytes = b64urlDecodeBytes(sigB64);
+    const okPrimary = await hmacVerify(env.JWT_SECRET, signingInput, sigBytes);
+    if (!okPrimary) {
+        if (env.JWT_SECRET_PREVIOUS) {
+            const okPrev = await hmacVerify(env.JWT_SECRET_PREVIOUS, signingInput, sigBytes);
+            if (!okPrev)
+                throw new NimbusTokenSignatureError();
+        }
+        else {
+            throw new NimbusTokenSignatureError();
+        }
+    }
+    // Decode + claim-shape validate.
+    let claims;
+    try {
+        claims = JSON.parse(b64urlDecodeString(payloadB64));
+    }
+    catch (e) {
+        throw new NimbusTokenMalformedError(`payload is not valid JSON: ${e?.message || e}`);
+    }
+    if (claims === null || typeof claims !== 'object') {
+        throw new NimbusTokenClaimsError('payload is not a JSON object');
+    }
+    if (claims.scope !== 'nimbus') {
+        throw new NimbusTokenClaimsError(`scope must be "nimbus" (got: ${JSON.stringify(claims.scope)})`);
+    }
+    if (typeof claims.tn !== 'string' || !ID_COMPONENT_RE.test(claims.tn)) {
+        throw new NimbusTokenClaimsError(`tn is missing or invalid`);
+    }
+    if (claims.sub !== undefined && (typeof claims.sub !== 'string' || !ID_COMPONENT_RE.test(claims.sub))) {
+        throw new NimbusTokenClaimsError(`sub shape invalid`);
+    }
+    if (claims.sid !== undefined && (typeof claims.sid !== 'string' || !ID_COMPONENT_RE.test(claims.sid))) {
+        throw new NimbusTokenClaimsError(`sid shape invalid`);
+    }
+    if (typeof claims.iat !== 'number' || typeof claims.exp !== 'number') {
+        throw new NimbusTokenClaimsError(`iat and exp must be numbers (NumericDate)`);
+    }
+    if (claims.scopes !== undefined) {
+        if (!Array.isArray(claims.scopes) || claims.scopes.some((s) => typeof s !== 'string')) {
+            throw new NimbusTokenClaimsError(`scopes must be an array of strings`);
+        }
+    }
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (claims.exp < nowSec) {
+        throw new NimbusTokenExpiredError(nowSec - claims.exp);
+    }
+    return {
+        claims,
+        doInstanceName: `${claims.tn}:${claims.sub ?? '_'}`,
+    };
+}
+// ── Internal helpers ─────────────────────────────────────────────────────
+/**
+ * HMAC-SHA-256 sign via WebCrypto subtle. Returns raw signature bytes.
+ *
+ * The CryptoKey is created on each call. workerd's subtle is cheap enough
+ * that caching would only matter at >10K signs/sec; we're at single-digit
+ * per request.
+ */
+async function hmacSha256(secret, data) {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data));
+    return new Uint8Array(sig);
+}
+/** Constant-time verify via `crypto.subtle.verify` (no manual loop needed). */
+async function hmacVerify(secret, data, expected) {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    return crypto.subtle.verify('HMAC', key, expected, new TextEncoder().encode(data));
+}
+/** base64url-encode a UTF-8 string. No padding. */
+function b64urlEncodeString(s) {
+    return b64urlEncodeBytes(new TextEncoder().encode(s));
+}
+/** base64url-encode raw bytes. No padding (per RFC 7515 §2). */
+function b64urlEncodeBytes(bytes) {
+    // workerd has btoa; convert bytes -> binary string -> btoa -> url-safe -> strip pad.
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** base64url-decode to a UTF-8 string. */
+function b64urlDecodeString(s) {
+    return new TextDecoder().decode(b64urlDecodeBytes(s));
+}
+/** base64url-decode to raw bytes. */
+function b64urlDecodeBytes(s) {
+    // Re-pad to a multiple of 4 + restore +/.
+    const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = (4 - (padded.length % 4)) % 4;
+    const padStr = padded + '='.repeat(pad);
+    const binary = atob(padStr);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * auth/types.ts — Public-facing types for the Nimbus auth surface.
+ *
+ * Two consumers:
+ *   1. The Worker (`@nimbus-sh/worker`) — reads `verifyNimbusToken` results
+ *      to gate `/s/<id>/` routes and pin DO instance names per-tenant.
+ *   2. The SDK (`@nimbus-sh/sdk`) — re-exports `issueNimbusToken` so an
+ *      embedder's Worker (or CLI) can mint tokens from a JWT secret.
+ *
+ * The on-the-wire shape is a JWS with HS256 signature, base64url-encoded:
+ *
+ *   <header>.<payload>.<signature>
+ *
+ * where the payload is a `NimbusTokenClaims` JSON object below. The header
+ * is the constant `{"alg":"HS256","typ":"JWT"}` — we don't permit alg
+ * variation (no `alg: "none"` confusion attack; we never read the header's
+ * `alg`).
+ */
+/**
+ * Claims encoded inside the JWT payload. Mirrors Mossaic's `{scope, ns, tn,
+ * sub?, sid?, iat, exp}` exactly except:
+ *   - `scope` is the literal string `"nimbus"`. Cross-product tokens
+ *     (e.g. a Mossaic VFS token) MUST be rejected by Nimbus's verifier.
+ *   - `tn` is the tenant. Required. Maps to the `tenant` portion of the
+ *     DO instance name. Per `[A-Za-z0-9._-]{1,128}` (validated at verify).
+ *   - `sub` is the user/principal within the tenant. Optional; when
+ *     absent, treated as `"_"` for DO naming (i.e. the tenant-default
+ *     user).
+ *   - `scopes` is an optional array of capability strings the token
+ *     grants. v1 honors `"session:create"`, `"session:attach"`,
+ *     `"session:admin"`. Absent = all permitted (backward compat for
+ *     legacy tokens).
+ *   - `sid` is an optional session-pin: when present, the token may only
+ *     attach to that single session. When absent, the token may attach
+ *     to any session for `(tn, sub)`.
+ *   - `iat` / `exp` are UNIX seconds (NumericDate per RFC 7519).
+ */
+export interface NimbusTokenClaims {
+    /** MUST be the literal `"nimbus"`. Discriminator vs Mossaic / other JWTs. */
+    scope: 'nimbus';
+    /** Tenant identifier. `[A-Za-z0-9._-]{1,128}`. */
+    tn: string;
+    /** Subject (user). Optional; absent = tenant-default. `[A-Za-z0-9._-]{1,128}`. */
+    sub?: string;
+    /** Capability scopes. Absent = legacy "all permitted". */
+    scopes?: string[];
+    /** Session-pin: token only valid for this session. Optional. */
+    sid?: string;
+    /** Issued-at (UNIX seconds). */
+    iat: number;
+    /** Expiry (UNIX seconds). */
+    exp: number;
+}
+/** Default token TTL when `issueNimbusToken` is called without `ttlMs`. 1 hour. */
+export declare const DEFAULT_TOKEN_TTL_MS: number;
+/** Maximum permitted token TTL. 30 days. Prevents accidental long-lived secrets. */
+export declare const MAX_TOKEN_TTL_MS: number;
+/**
+ * Result of a successful `verifyNimbusToken` call. Verified claims plus a
+ * canonical DO instance-naming string derived from `(tn, sub || '_')`.
+ *
+ * Consumers should prefer `doInstanceName` over re-deriving from `claims`
+ * — the verifier is the single source of truth for sub-defaulting.
+ */
+export interface VerifiedNimbusToken {
+    /** The verified claims, unchanged from the wire format. */
+    claims: NimbusTokenClaims;
+    /** `${tn}:${sub || '_'}` — feed to `idFromName` after appending sessionId. */
+    doInstanceName: string;
+}
+/**
+ * Options for `issueNimbusToken`. All optional.
+ *
+ * `ttlMs` defaults to {@link DEFAULT_TOKEN_TTL_MS}. Values > {@link
+ * MAX_TOKEN_TTL_MS} throw `NimbusAuthError` with `code: 'TTL_TOO_LARGE'`.
+ */
+export interface IssueTokenOptions {
+    ttlMs?: number;
+    /** Override `iat`. Useful in tests to assert exp arithmetic. */
+    iatOverride?: number;
+}
+/**
+ * Base error class for every auth-layer failure. Subclasses encode the
+ * specific failure mode in `code`.
+ *
+ * Why a class hierarchy instead of an `{ ok: false, code }` union? Two
+ * reasons: (1) embedders' error handlers naturally use `try/catch`, and
+ * an exception flow propagates without ceremony; (2) consumers in
+ * non-TypeScript environments (a Node SSR layer minting tokens) still
+ * get `error.code` introspection.
+ *
+ * Every subclass below is INSTANCEOF-compatible with this base, so a
+ * blanket `catch (e instanceof NimbusAuthError)` works.
+ */
+export declare class NimbusAuthError extends Error {
+    /** Machine-readable code for catch sites. Subclass-stable. */
+    readonly code: string;
+    /** HTTP status the embedder's auth gate should map to (typically 401). */
+    readonly httpStatus: number;
+    constructor(message: string, code: string, httpStatus?: number);
+}
+/** Thrown when JWT_SECRET env var is missing at issue/verify time. */
+export declare class NimbusAuthConfigError extends NimbusAuthError {
+    constructor(message?: string);
+}
+/** Thrown when the token shape is structurally invalid (not 3 parts, bad b64). */
+export declare class NimbusTokenMalformedError extends NimbusAuthError {
+    constructor(reason: string);
+}
+/** Thrown when the HMAC signature does not verify against JWT_SECRET. */
+export declare class NimbusTokenSignatureError extends NimbusAuthError {
+    constructor();
+}
+/** Thrown when claims fail validation (missing scope, bad tn shape, etc.). */
+export declare class NimbusTokenClaimsError extends NimbusAuthError {
+    constructor(reason: string);
+}
+/** Thrown when `exp` is in the past (with no clock skew tolerance — strict). */
+export declare class NimbusTokenExpiredError extends NimbusAuthError {
+    /** Seconds the token expired ago (always ≥ 0). */
+    readonly expiredAgoSec: number;
+    constructor(expiredAgoSec: number);
+}
+/** Thrown when issue-time ttl exceeds {@link MAX_TOKEN_TTL_MS}. */
+export declare class NimbusTokenTtlError extends NimbusAuthError {
+    constructor(ttlMs: number, maxMs: number);
+}
+/** Thrown when a route requires a scope the token doesn't carry. */
+export declare class NimbusScopeError extends NimbusAuthError {
+    readonly requiredScope: string;
+    constructor(requiredScope: string);
+}
+/** Thrown when sid-pin doesn't match the actual session being attached. */
+export declare class NimbusSessionPinError extends NimbusAuthError {
+    readonly pinnedTo: string;
+    readonly attempted: string;
+    constructor(pinnedTo: string, attempted: string);
+}
+/** Regex used to validate the `tn` and `sub` shape (per Mossaic §7.1). */
+export declare const ID_COMPONENT_RE: RegExp;
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,KAAK,EAAE,QAAQ,CAAC;IAChB,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAEnD,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,QAA2B,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY;CAMpE;AAED,sEAAsE;AACtE,qBAAa,qBAAsB,SAAQ,eAAe;gBAC5C,OAAO,GAAE,MAAuC;CAI7D;AAED,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,eAAe;gBAChD,MAAM,EAAE,MAAM;CAI3B;AAED,yEAAyE;AACzE,qBAAa,yBAA0B,SAAQ,eAAe;;CAK7D;AAED,8EAA8E;AAC9E,qBAAa,sBAAuB,SAAQ,eAAe;gBAC7C,MAAM,EAAE,MAAM;CAI3B;AAED,gFAAgF;AAChF,qBAAa,uBAAwB,SAAQ,eAAe;IAC1D,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,aAAa,EAAE,MAAM;CAKlC;AAED,mEAAmE;AACnE,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAQzC;AAED,oEAAoE;AACpE,qBAAa,gBAAiB,SAAQ,eAAe;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,aAAa,EAAE,MAAM;CAKlC;AAED,2EAA2E;AAC3E,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAUhD;AAED,0EAA0E;AAC1E,eAAO,MAAM,eAAe,QAA4B,CAAC"}