@zauso-ai/capstan-auth 0.1.2

package/dist/api-key.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Generate a new API key suitable for agent authentication.
+ *
+ * Returns:
+ * - `key`    — the full plaintext key (show once to the user, never store)
+ * - `hash`   — SHA-256 hex digest of the key (store in the database)
+ * - `prefix` — short prefix of the key for fast DB look-up
+ */
+export declare function generateApiKey(prefix?: string): {
+    key: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * Verify a plaintext API key against a stored SHA-256 hash.
+ *
+ * Uses timing-safe comparison to prevent timing side-channel attacks.
+ */
+export declare function verifyApiKey(key: string, storedHash: string): Promise<boolean>;
+/**
+ * Extract the lookup prefix from a full plaintext API key.
+ *
+ * This prefix can be used to find the matching credential row in the
+ * database without hashing first (the hash is checked afterwards).
+ */
+export declare function extractApiKeyPrefix(key: string): string;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAYA;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASvD"}

package/dist/api-key.js

@@ -0,0 +1,60 @@
+import { randomBytes, createHash, timingSafeEqual, } from "node:crypto";
+const DEFAULT_PREFIX = "cap_ak_";
+/**
+ * The number of random hex characters appended after the prefix.
+ * 32 hex chars = 16 bytes = 128 bits of entropy.
+ */
+const RANDOM_HEX_LENGTH = 32;
+/**
+ * Number of characters from the full key used as a short "prefix" for
+ * database look-up (prefix of the *random* portion, after the key prefix).
+ */
+const LOOKUP_PREFIX_LENGTH = 8;
+// ── Public API ─────────────────────────────────────────────────────
+/**
+ * Generate a new API key suitable for agent authentication.
+ *
+ * Returns:
+ * - `key`    — the full plaintext key (show once to the user, never store)
+ * - `hash`   — SHA-256 hex digest of the key (store in the database)
+ * - `prefix` — short prefix of the key for fast DB look-up
+ */
+export function generateApiKey(prefix) {
+    const keyPrefix = prefix ?? DEFAULT_PREFIX;
+    const randomPart = randomBytes(RANDOM_HEX_LENGTH / 2).toString("hex");
+    const key = `${keyPrefix}${randomPart}`;
+    const hash = createHash("sha256").update(key).digest("hex");
+    // The lookup prefix is the key prefix + the first LOOKUP_PREFIX_LENGTH
+    // chars of the random portion, giving enough uniqueness for a DB index.
+    const lookupPrefix = `${keyPrefix}${randomPart.slice(0, LOOKUP_PREFIX_LENGTH)}`;
+    return { key, hash, prefix: lookupPrefix };
+}
+/**
+ * Verify a plaintext API key against a stored SHA-256 hash.
+ *
+ * Uses timing-safe comparison to prevent timing side-channel attacks.
+ */
+export async function verifyApiKey(key, storedHash) {
+    const candidateHash = createHash("sha256").update(key).digest("hex");
+    const a = Buffer.from(candidateHash, "utf-8");
+    const b = Buffer.from(storedHash, "utf-8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * Extract the lookup prefix from a full plaintext API key.
+ *
+ * This prefix can be used to find the matching credential row in the
+ * database without hashing first (the hash is checked afterwards).
+ */
+export function extractApiKeyPrefix(key) {
+    // Detect the structural prefix (everything before the random hex).
+    // We look for the pattern: one or more segments ending with "_" followed
+    // by hex characters.
+    const structuralMatch = key.match(/^([a-zA-Z0-9]+(?:_[a-zA-Z0-9]+)*_)/);
+    const structuralPrefix = structuralMatch?.[1] ?? DEFAULT_PREFIX;
+    const randomPart = key.slice(structuralPrefix.length);
+    return `${structuralPrefix}${randomPart.slice(0, LOOKUP_PREFIX_LENGTH)}`;
+}
+//# sourceMappingURL=api-key.js.map

package/dist/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC;;;GAGG;AACH,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;GAGG;AACH,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B,sEAAsE;AAEtE;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAK5C,MAAM,SAAS,GAAG,MAAM,IAAI,cAAc,CAAC;IAC3C,MAAM,UAAU,GAAG,WAAW,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtE,MAAM,GAAG,GAAG,GAAG,SAAS,GAAG,UAAU,EAAE,CAAC;IAExC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE5D,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,YAAY,GAAG,GAAG,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,EAAE,CAAC;IAEhF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,UAAkB;IAElB,MAAM,aAAa,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAErE,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAE3C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAExC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,mEAAmE;IACnE,yEAAyE;IACzE,qBAAqB;IACrB,MAAM,eAAe,GAAG,GAAG,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxE,MAAM,gBAAgB,GAAG,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC;IAChE,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEtD,OAAO,GAAG,gBAAgB,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,EAAE,CAAC;AAC3E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { signSession, verifySession } from "./session.js";
+export { generateApiKey, verifyApiKey, extractApiKeyPrefix, } from "./api-key.js";
+export { createAuthMiddleware } from "./middleware.js";
+export { checkPermission, derivePermission } from "./permissions.js";
+export type { AuthConfig, SessionPayload, AgentCredential, AuthContext, AuthResolverDeps, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { signSession, verifySession } from "./session.js";
+export { generateApiKey, verifyApiKey, extractApiKeyPrefix, } from "./api-key.js";
+export { createAuthMiddleware } from "./middleware.js";
+export { checkPermission, derivePermission } from "./permissions.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,14 @@
+import type { AuthConfig, AuthContext, AuthResolverDeps } from "./types.js";
+/**
+ * Create a middleware function that resolves an `AuthContext` from an
+ * incoming `Request`.
+ *
+ * Resolution order:
+ * 1. Session cookie (`capstan_session`) — verifies JWT, returns human context.
+ * 2. `Authorization: Bearer <token>` header — if the token matches the
+ *    configured API key prefix, looks up the agent credential and verifies
+ *    the key hash.
+ * 3. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
+ */
+export declare function createAuthMiddleware(config: AuthConfig, deps: AuthResolverDeps): (request: Request) => Promise<AuthContext>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA2BpB;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,gBAAgB,GACrB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,WAAW,CAAC,CAuD5C"}

package/dist/middleware.js

@@ -0,0 +1,86 @@
+import { verifySession } from "./session.js";
+import { verifyApiKey, extractApiKeyPrefix } from "./api-key.js";
+const SESSION_COOKIE_NAME = "capstan_session";
+const DEFAULT_API_KEY_PREFIX = "cap_ak_";
+const ANONYMOUS_CONTEXT = {
+    isAuthenticated: false,
+    type: "anonymous",
+};
+// ── Cookie helpers ─────────────────────────────────────────────────
+function parseCookies(header) {
+    const cookies = new Map();
+    for (const pair of header.split(";")) {
+        const eqIndex = pair.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const name = pair.slice(0, eqIndex).trim();
+        const value = pair.slice(eqIndex + 1).trim();
+        cookies.set(name, value);
+    }
+    return cookies;
+}
+// ── Middleware factory ──────────────────────────────────────────────
+/**
+ * Create a middleware function that resolves an `AuthContext` from an
+ * incoming `Request`.
+ *
+ * Resolution order:
+ * 1. Session cookie (`capstan_session`) — verifies JWT, returns human context.
+ * 2. `Authorization: Bearer <token>` header — if the token matches the
+ *    configured API key prefix, looks up the agent credential and verifies
+ *    the key hash.
+ * 3. Falls back to `{ type: "anonymous", isAuthenticated: false }`.
+ */
+export function createAuthMiddleware(config, deps) {
+    const apiKeyPrefix = config.apiKeys?.prefix ?? DEFAULT_API_KEY_PREFIX;
+    const authHeaderName = config.apiKeys?.headerName ?? "Authorization";
+    return async (request) => {
+        // ── 1. Session cookie ────────────────────────────────────────
+        const cookieHeader = request.headers.get("cookie");
+        if (cookieHeader) {
+            const cookies = parseCookies(cookieHeader);
+            const sessionToken = cookies.get(SESSION_COOKIE_NAME);
+            if (sessionToken) {
+                const payload = verifySession(sessionToken, config.session.secret);
+                if (payload) {
+                    const ctx = {
+                        isAuthenticated: true,
+                        type: "human",
+                        userId: payload.userId,
+                    };
+                    if (payload.role !== undefined)
+                        ctx.role = payload.role;
+                    if (payload.email !== undefined)
+                        ctx.email = payload.email;
+                    return ctx;
+                }
+            }
+        }
+        // ── 2. API key via Authorization header ──────────────────────
+        const authHeader = request.headers.get(authHeaderName);
+        if (authHeader) {
+            const token = authHeader.startsWith("Bearer ")
+                ? authHeader.slice(7)
+                : null;
+            if (token && token.startsWith(apiKeyPrefix) && deps.findAgentByKeyPrefix) {
+                const prefix = extractApiKeyPrefix(token);
+                const credential = await deps.findAgentByKeyPrefix(prefix);
+                if (credential && !credential.revokedAt) {
+                    const valid = await verifyApiKey(token, credential.apiKeyHash);
+                    if (valid) {
+                        return {
+                            isAuthenticated: true,
+                            type: "agent",
+                            agentId: credential.id,
+                            agentName: credential.name,
+                            permissions: credential.permissions,
+                        };
+                    }
+                }
+            }
+        }
+        // ── 3. Anonymous ─────────────────────────────────────────────
+        return ANONYMOUS_CONTEXT;
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/permissions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Check whether a required permission is satisfied by at least one entry in
+ * the `granted` permission set.
+ *
+ * Permission strings follow the `resource:action` pattern.
+ *
+ * Wildcards:
+ * - `*:read`  — allows `read` on any resource
+ * - `ticket:*` — allows any action on `ticket`
+ * - `*:*`     — full access (superuser)
+ *
+ * Examples:
+ *   checkPermission({ resource: "ticket", action: "read" }, ["ticket:read"])  // true
+ *   checkPermission({ resource: "ticket", action: "write" }, ["*:write"])     // true
+ *   checkPermission({ resource: "ticket", action: "delete" }, ["ticket:*"])   // true
+ *   checkPermission({ resource: "ticket", action: "delete" }, ["*:*"])        // true
+ */
+export declare function checkPermission(required: {
+    resource: string;
+    action: "read" | "write" | "delete";
+}, granted: string[]): boolean;
+/**
+ * Derive a `{ resource, action }` pair from an agent capability mode and
+ * an optional resource name.
+ *
+ * Mapping:
+ * - `"read"`     → `{ resource, action: "read" }`
+ * - `"write"`    → `{ resource, action: "write" }`
+ * - `"external"` → `{ resource: "external", action: "write" }`
+ *
+ * When `resource` is omitted the wildcard `"*"` is used.
+ */
+export declare function derivePermission(capability: "read" | "write" | "external", resource?: string): {
+    resource: string;
+    action: string;
+};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;CAAE,EACnE,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAiBT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,EACzC,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAStC"}

package/dist/permissions.js

@@ -0,0 +1,52 @@
+/**
+ * Check whether a required permission is satisfied by at least one entry in
+ * the `granted` permission set.
+ *
+ * Permission strings follow the `resource:action` pattern.
+ *
+ * Wildcards:
+ * - `*:read`  — allows `read` on any resource
+ * - `ticket:*` — allows any action on `ticket`
+ * - `*:*`     — full access (superuser)
+ *
+ * Examples:
+ *   checkPermission({ resource: "ticket", action: "read" }, ["ticket:read"])  // true
+ *   checkPermission({ resource: "ticket", action: "write" }, ["*:write"])     // true
+ *   checkPermission({ resource: "ticket", action: "delete" }, ["ticket:*"])   // true
+ *   checkPermission({ resource: "ticket", action: "delete" }, ["*:*"])        // true
+ */
+export function checkPermission(required, granted) {
+    for (const perm of granted) {
+        const sepIndex = perm.indexOf(":");
+        if (sepIndex === -1)
+            continue; // malformed entry, skip
+        const grantedResource = perm.slice(0, sepIndex);
+        const grantedAction = perm.slice(sepIndex + 1);
+        const resourceMatch = grantedResource === "*" || grantedResource === required.resource;
+        const actionMatch = grantedAction === "*" || grantedAction === required.action;
+        if (resourceMatch && actionMatch)
+            return true;
+    }
+    return false;
+}
+/**
+ * Derive a `{ resource, action }` pair from an agent capability mode and
+ * an optional resource name.
+ *
+ * Mapping:
+ * - `"read"`     → `{ resource, action: "read" }`
+ * - `"write"`    → `{ resource, action: "write" }`
+ * - `"external"` → `{ resource: "external", action: "write" }`
+ *
+ * When `resource` is omitted the wildcard `"*"` is used.
+ */
+export function derivePermission(capability, resource) {
+    if (capability === "external") {
+        return { resource: "external", action: "write" };
+    }
+    return {
+        resource: resource ?? "*",
+        action: capability,
+    };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAmE,EACnE,OAAiB;IAEjB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,SAAS,CAAC,wBAAwB;QAEvD,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;QAE/C,MAAM,aAAa,GACjB,eAAe,KAAK,GAAG,IAAI,eAAe,KAAK,QAAQ,CAAC,QAAQ,CAAC;QACnE,MAAM,WAAW,GACf,aAAa,KAAK,GAAG,IAAI,aAAa,KAAK,QAAQ,CAAC,MAAM,CAAC;QAE7D,IAAI,aAAa,IAAI,WAAW;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAyC,EACzC,QAAiB;IAEjB,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACnD,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ,IAAI,GAAG;QACzB,MAAM,EAAE,UAAU;KACnB,CAAC;AACJ,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,15 @@
+import type { SessionPayload } from "./types.js";
+/**
+ * Create a signed JWT containing the given session data.
+ *
+ * `maxAge` defaults to `"7d"` (7 days) when omitted.
+ */
+export declare function signSession(payload: Omit<SessionPayload, "iat" | "exp">, secret: string, maxAge?: string): string;
+/**
+ * Verify a JWT's HMAC-SHA256 signature and expiration.
+ *
+ * Returns the decoded payload on success, or `null` when the token is
+ * invalid, tampered with, or expired.
+ */
+export declare function verifySession(token: string, secret: string): SessionPayload | null;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA+DjD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,KAAK,CAAC,EAC5C,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAWR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,IAAI,CA6BvB"}

package/dist/session.js

@@ -0,0 +1,95 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+// ── Base64url helpers ──────────────────────────────────────────────
+function base64urlEncode(data) {
+    const buf = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
+    return buf.toString("base64url");
+}
+function base64urlDecode(str) {
+    return Buffer.from(str, "base64url").toString("utf-8");
+}
+// ── Duration parsing ───────────────────────────────────────────────
+/**
+ * Parse a human-friendly duration string into seconds.
+ *
+ * Supported suffixes:
+ *   "s" — seconds   "m" — minutes   "h" — hours   "d" — days   "w" — weeks
+ *
+ * Examples: "7d" → 604800, "1h" → 3600, "30m" → 1800
+ */
+function parseDuration(duration) {
+    const match = duration.match(/^(\d+)\s*(s|m|h|d|w)$/);
+    if (!match) {
+        throw new Error(`Invalid duration format: "${duration}". Expected a number followed by s, m, h, d, or w.`);
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const multipliers = {
+        s: 1,
+        m: 60,
+        h: 3600,
+        d: 86_400,
+        w: 604_800,
+    };
+    return value * multipliers[unit];
+}
+// ── JWT implementation (HS256) ─────────────────────────────────────
+function sign(payload, secret) {
+    const header = base64urlEncode(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+    const body = base64urlEncode(payload);
+    const signingInput = `${header}.${body}`;
+    const signature = createHmac("sha256", secret)
+        .update(signingInput)
+        .digest();
+    return `${signingInput}.${base64urlEncode(signature)}`;
+}
+// ── Public API ─────────────────────────────────────────────────────
+/**
+ * Create a signed JWT containing the given session data.
+ *
+ * `maxAge` defaults to `"7d"` (7 days) when omitted.
+ */
+export function signSession(payload, secret, maxAge) {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const ttl = parseDuration(maxAge ?? "7d");
+    const full = {
+        ...payload,
+        iat: nowSeconds,
+        exp: nowSeconds + ttl,
+    };
+    return sign(JSON.stringify(full), secret);
+}
+/**
+ * Verify a JWT's HMAC-SHA256 signature and expiration.
+ *
+ * Returns the decoded payload on success, or `null` when the token is
+ * invalid, tampered with, or expired.
+ */
+export function verifySession(token, secret) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const [header, body, sig] = parts;
+    // Recompute the expected signature.
+    const expectedSig = createHmac("sha256", secret)
+        .update(`${header}.${body}`)
+        .digest();
+    const actualSig = Buffer.from(sig, "base64url");
+    // Timing-safe comparison to prevent timing attacks.
+    if (expectedSig.length !== actualSig.length)
+        return null;
+    if (!timingSafeEqual(expectedSig, actualSig))
+        return null;
+    // Decode payload.
+    try {
+        const payload = JSON.parse(base64urlDecode(body));
+        // Check expiration.
+        const now = Math.floor(Date.now() / 1000);
+        if (typeof payload.exp !== "number" || payload.exp <= now)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,sEAAsE;AAEtE,SAAS,eAAe,CAAC,IAAqB;IAC5C,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,OAAO,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,sEAAsE;AAEtE;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,6BAA6B,QAAQ,oDAAoD,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAgC,CAAC;IAErD,MAAM,WAAW,GAA2B;QAC1C,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,EAAE;QACL,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,OAAO;KACX,CAAC;IAEF,OAAO,KAAK,GAAG,WAAW,CAAC,IAAI,CAAE,CAAC;AACpC,CAAC;AAED,sEAAsE;AAEtE,SAAS,IAAI,CAAC,OAAe,EAAE,MAAc;IAC3C,MAAM,MAAM,GAAG,eAAe,CAC5B,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAC7C,CAAC;IACF,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;IAEzC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC3C,MAAM,CAAC,YAAY,CAAC;SACpB,MAAM,EAAE,CAAC;IAEZ,OAAO,GAAG,YAAY,IAAI,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,sEAAsE;AAEtE;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,OAA4C,EAC5C,MAAc,EACd,MAAe;IAEf,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;IAE1C,MAAM,IAAI,GAAmB;QAC3B,GAAG,OAAO;QACV,GAAG,EAAE,UAAU;QACf,GAAG,EAAE,UAAU,GAAG,GAAG;KACtB,CAAC;IAEF,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,MAAc;IAEd,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,KAAiC,CAAC;IAE9D,oCAAoC;IACpC,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC7C,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;SAC3B,MAAM,EAAE,CAAC;IAEZ,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAEhD,oDAAoD;IACpD,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1D,kBAAkB;IAClB,IAAI,CAAC;QACH,MAAM,OAAO,GAAmB,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAElE,oBAAoB;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,IAAI,GAAG;YAAE,OAAO,IAAI,CAAC;QAEvE,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+export interface AuthConfig {
+    session: {
+        secret: string;
+        maxAge?: string;
+    };
+    apiKeys?: {
+        prefix?: string;
+        headerName?: string;
+    };
+}
+export interface SessionPayload {
+    userId: string;
+    email?: string;
+    role?: string;
+    iat: number;
+    exp: number;
+}
+export interface AgentCredential {
+    id: string;
+    name: string;
+    apiKeyHash: string;
+    apiKeyPrefix: string;
+    permissions: string[];
+    revokedAt?: string;
+}
+export interface AuthContext {
+    isAuthenticated: boolean;
+    type: "human" | "agent" | "anonymous";
+    userId?: string;
+    role?: string;
+    email?: string;
+    agentId?: string;
+    agentName?: string;
+    permissions?: string[];
+}
+export interface AuthResolverDeps {
+    /** Look up an agent credential by API key prefix */
+    findAgentByKeyPrefix?: (prefix: string) => Promise<AgentCredential | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACtC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zauso-ai/capstan-auth",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "description": "Authentication for Capstan — JWT sessions, API key auth for AI agents, permissions",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/barry3406/capstan.git",
+    "directory": "packages/auth"
+  },
+  "license": "MIT",
+  "author": "barry3406",
+  "homepage": "https://github.com/barry3406/capstan",
+  "keywords": [
+    "capstan",
+    "ai-agent",
+    "full-stack",
+    "framework",
+    "mcp",
+    "a2a",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}