@azlib/identity 0.2.1 → 0.3.1

package/README.md

@@ -9,13 +9,14 @@ you can plug the package into your own database engine and transport layer.
 
 ## Entry points
 
-| Import | Purpose |
-| --- | --- |
-| `@azlib/identity` | Framework-agnostic types, config, errors, authorization, store contract |
-| `@azlib/identity/node` | Node runtime services (password hashing, JWT, register/login/refresh) |
-| `@azlib/identity/express` | Express authentication and authorization middleware |
-| `@azlib/identity/nestjs` | NestJS module, guards, and decorators |
-| `@azlib/identity/schema/*` | Predefined SQL and Prisma schema artifacts |
+| Import                     | Purpose                                                                 |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `@azlib/identity`          | Framework-agnostic types, config, errors, authorization, store contract, Edge-safe JWT verify and cookie presence helpers |
+| `@azlib/identity/node`     | Node runtime services (password hashing, JWT, register/login/refresh)   |
+| `@azlib/identity/express`  | Express authentication and authorization middleware                     |
+| `@azlib/identity/nestjs`   | NestJS module, guards, and decorators                                   |
+| `@azlib/identity/next`     | Next.js / Fetch HttpOnly cookie sessions, `getIdentity`, Route Handlers |
+| `@azlib/identity/schema/*` | Predefined SQL and Prisma schema artifacts                              |
 
 ## Quick start (Express)
 
@@ -33,7 +34,10 @@ you can plug the package into your own database engine and transport layer.
    ```ts
    import express from "express";
    import { createIdentityService } from "@azlib/identity/node";
-   import { createIdentityRouter, identityErrorHandler } from "@azlib/identity/express";
+   import {
+     createIdentityRouter,
+     identityErrorHandler,
+   } from "@azlib/identity/express";
 
    const service = createIdentityService(
      { accessTokenSecret: process.env.ACCESS_TOKEN_SECRET! },
@@ -48,15 +52,15 @@ you can plug the package into your own database engine and transport layer.
 
    That's it. The following endpoints are ready immediately:
 
-   | Method | Path | Description |
-   |--------|------|-------------|
-   | `POST` | `/auth/register` | Create a new account |
-   | `POST` | `/auth/login` | Email + password login |
-   | `POST` | `/auth/refresh` | Rotate the refresh token |
-   | `POST` | `/auth/logout` | Revoke the session |
-   | `GET`  | `/auth/me` | Return the authenticated principal |
-   | `GET`  | `/auth/:provider` | Start an OAuth flow *(if configured)* |
-   | `GET`  | `/auth/:provider/callback` | Handle an OAuth callback *(if configured)* |
+   | Method | Path                       | Description                                |
+   | ------ | -------------------------- | ------------------------------------------ |
+   | `POST` | `/auth/register`           | Create a new account                       |
+   | `POST` | `/auth/login`              | Email + password login                     |
+   | `POST` | `/auth/refresh`            | Rotate the refresh token                   |
+   | `POST` | `/auth/logout`             | Revoke the session                         |
+   | `GET`  | `/auth/me`                 | Return the authenticated principal         |
+   | `GET`  | `/auth/:provider`          | Start an OAuth flow _(if configured)_      |
+   | `GET`  | `/auth/:provider/callback` | Handle an OAuth callback _(if configured)_ |
 
 ### Cookie-mode refresh tokens
 
@@ -85,7 +89,7 @@ const service = createIdentityService(
     oauth: {
       providers: [
         createGoogleOAuthProvider({
-          clientId:     process.env.GOOGLE_CLIENT_ID!,
+          clientId: process.env.GOOGLE_CLIENT_ID!,
           clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
         }),
       ],
@@ -127,7 +131,10 @@ Authorization is **deny-by-default**: a principal is only allowed when an explic
 through an assigned role; both resolve into the principal's `permissions`.
 
 ```ts
-import { requirePermission, requireAuthorization } from "@azlib/identity/express";
+import {
+  requirePermission,
+  requireAuthorization,
+} from "@azlib/identity/express";
 
 // Require a single permission.
 app.get(
@@ -145,7 +152,8 @@ app.delete(
     identity,
     {
       permission: "documents:delete",
-      policy: ({ principal, resource }) => resource.ownerId === principal.userId,
+      policy: ({ principal, resource }) =>
+        resource.ownerId === principal.userId,
     },
     (req) => loadDocument(req.params.id),
   ),
@@ -156,7 +164,10 @@ app.delete(
 Grant roles and permissions through the store contract:
 
 ```ts
-await store.grantRolePermission({ roleId: "editor", permission: "documents:write" });
+await store.grantRolePermission({
+  roleId: "editor",
+  permission: "documents:write",
+});
 await store.assignRole({ userId, roleId: "editor" });
 await store.grantDirectPermission({ userId, permission: "reports:read" });
 ```
@@ -194,7 +205,7 @@ IdentityModule.forRoot({
     prefix: "v1/auth",
     cookie: { name: "rt", secure: true },
   },
-})
+});
 ```
 
 ### Guards and decorators
@@ -221,6 +232,49 @@ A runnable NestJS app lives in [`examples/nest-basic`](./examples/nest-basic). T
 `IdentityService` core powers both the Express and NestJS adapters, so behavior is
 identical across frameworks.
 
+## Next.js (App Router)
+
+Cookie-based sessions for Server Components, Server Actions, and Route Handlers.
+Both the access JWT and the rotating refresh token are stored as `HttpOnly` cookies
+(`azlib_at` / `azlib_rt` by default). Roles and tenant data stay out of the JWT —
+hydrate those in your app after `getIdentity()`.
+
+```ts
+import { cookies } from "next/headers";
+import { createIdentityService } from "@azlib/identity/node";
+import {
+  applyAuthCookies,
+  clearAuthCookies,
+  getIdentity,
+  hasIdentityCookies,
+} from "@azlib/identity/next";
+
+const identity = createIdentityService(config, store);
+
+// Server Action — login
+const result = await identity.login({ email, password });
+if (!("kind" in result)) {
+  applyAuthCookies(await cookies(), result.tokens);
+}
+
+// Server Component / Server Action — current principal
+const principal = await getIdentity(identity, await cookies());
+
+// proxy.ts (Edge) — presence only, no database
+if (pathname.startsWith("/admin") && !hasIdentityCookies(request.headers)) {
+  return NextResponse.redirect(loginUrl);
+}
+
+// Optional Route Handlers
+import { createIdentityHandlers } from "@azlib/identity/next";
+export const { login: POST } = createIdentityHandlers(identity);
+```
+
+`getIdentity` authenticates a valid access cookie, or silently refreshes when the
+access token is expired. Refresh rotates the refresh token, so call it where cookies
+can be written (Server Actions and Route Handlers). `verifyAccessToken` from
+`@azlib/identity` is Edge-safe if you need to inspect JWT claims without Node.
+
 ## Account lockout
 
 Protect against brute-force credential attacks by automatically locking accounts after too many consecutive failed logins.
@@ -230,8 +284,8 @@ createIdentityService(
   {
     accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
     lockout: {
-      maxFailedAttempts: 5,   // 0 = disabled (default: 10)
-      durationSeconds:  900,  // 0 = permanent lock (default: 900 = 15 min)
+      maxFailedAttempts: 5, // 0 = disabled (default: 10)
+      durationSeconds: 900, // 0 = permanent lock (default: 900 = 15 min)
     },
   },
   store,
@@ -268,13 +322,13 @@ const identity = createIdentityService(
     oauth: {
       providers: [
         createGoogleOAuthProvider({
-          clientId:     process.env.GOOGLE_CLIENT_ID!,
+          clientId: process.env.GOOGLE_CLIENT_ID!,
           clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
         }),
         createMicrosoftOAuthProvider({
-          clientId:     process.env.MS_CLIENT_ID!,
+          clientId: process.env.MS_CLIENT_ID!,
           clientSecret: process.env.MS_CLIENT_SECRET!,
-          tenantId:     "common",          // or a specific tenant UUID
+          tenantId: "common", // or a specific tenant UUID
         }),
       ],
     },
@@ -283,15 +337,18 @@ const identity = createIdentityService(
 );
 
 // identity.oauth is an OAuthService when providers are configured.
-const { url, state } = identity.oauth!.buildAuthorizationUrl("google", REDIRECT_URI);
+const { url, state } = identity.oauth!.buildAuthorizationUrl(
+  "google",
+  REDIRECT_URI,
+);
 // …redirect the user to `url`, persist `state` in a signed cookie/session
 
 // In the callback handler:
 const result = await identity.oauth!.handleCallback("google", {
-  code:          req.query.code as string,
-  state:         req.query.state as string,
+  code: req.query.code as string,
+  state: req.query.state as string,
   expectedState: req.session.oauthState,
-  redirectUri:   REDIRECT_URI,
+  redirectUri: REDIRECT_URI,
 });
 // result.tokens.accessToken is now ready
 ```
@@ -303,13 +360,18 @@ import { oauthAuthorize, oauthCallback } from "@azlib/identity/express";
 
 const options = {
   redirectUri: `${BASE_URL}/auth/google/callback`,
-  getState:    (req) => req.session?.oauthState ?? null,
-  setState:    (req, _res, state) => { req.session!.oauthState = state; },
-  onSuccess:   (_req, res, result) => res.json(result),
+  getState: (req) => req.session?.oauthState ?? null,
+  setState: (req, _res, state) => {
+    req.session!.oauthState = state;
+  },
+  onSuccess: (_req, res, result) => res.json(result),
 };
 
-app.get("/auth/google",          oauthAuthorize(identity.oauth!, "google", options));
-app.get("/auth/google/callback", oauthCallback(identity.oauth!,  "google", options));
+app.get("/auth/google", oauthAuthorize(identity.oauth!, "google", options));
+app.get(
+  "/auth/google/callback",
+  oauthCallback(identity.oauth!, "google", options),
+);
 ```
 
 ### Callback flow
@@ -325,8 +387,6 @@ Your `IdentityStore` should implement the optional `findUserByOAuthId`, `createO
 `listOAuthLinks` methods for full OAuth support. The shipped schema artifacts include the
 `identity_oauth_linked_accounts` table.
 
-
-
 The package never talks to a database directly — you provide an `IdentityStore`. Two
 adoption paths:
 
@@ -381,16 +441,18 @@ createIdentityService(
 
 ### Core Exports
 
-| Entry Point / Import | Export | Type | Description |
-| --- | --- | --- | --- |
-| `@azlib/identity` | `evaluateAuthorization` | Function | Evaluates custom permission requirements against a user principal. |
-| `@azlib/identity` | `identitySchemaModel` | Object | Relation structures and constraints definitions. |
-| `@azlib/identity/node` | `createIdentityService` | Function | Instantiates the core user authentication / registration service. |
-| `@azlib/identity/node` | `createGoogleOAuthProvider` | Function | Factory for Google OAuth provider link configurations. |
-| `@azlib/identity/express` | `createIdentityRouter` | Function | Mountable Express router containing all login/register endpoints. |
-| `@azlib/identity/express` | `requireAuth` | Middleware | Express middleware checking request Bearer token authorization. |
-| `@azlib/identity/express` | `requirePermission` | Middleware | Express middleware restricting actions to specific permissions. |
-| `@azlib/identity/nestjs` | `IdentityModule` | NestJS Module | Core NestJS DI registration boundary. |
+| Entry Point / Import      | Export                      | Type          | Description                                                        |
+| ------------------------- | --------------------------- | ------------- | ------------------------------------------------------------------ |
+| `@azlib/identity`         | `evaluateAuthorization`     | Function      | Evaluates custom permission requirements against a user principal. |
+| `@azlib/identity`         | `identitySchemaModel`       | Object        | Relation structures and constraints definitions.                   |
+| `@azlib/identity/node`    | `createIdentityService`     | Function      | Instantiates the core user authentication / registration service.  |
+| `@azlib/identity/node`    | `createGoogleOAuthProvider` | Function      | Factory for Google OAuth provider link configurations.             |
+| `@azlib/identity/express` | `createIdentityRouter`      | Function      | Mountable Express router containing all login/register endpoints.  |
+| `@azlib/identity/express` | `requireAuth`               | Middleware    | Express middleware checking request Bearer token authorization.    |
+| `@azlib/identity/express` | `requirePermission`         | Middleware    | Express middleware restricting actions to specific permissions.    |
+| `@azlib/identity/next`    | `getIdentity`               | Function      | Resolve the principal from access/refresh cookies, with silent refresh. |
+| `@azlib/identity/next`    | `hasIdentityCookies`        | Function      | Edge-safe check that identity cookies are present.                 |
+| `@azlib/identity/nestjs`  | `IdentityModule`            | NestJS Module | Core NestJS DI registration boundary.                              |
 
 ### Core Types
 
@@ -408,23 +470,26 @@ createIdentityService(
 import { createIdentityService } from "@azlib/identity/node";
 import { createIdentityRouter } from "@azlib/identity/express";
 
-const service = createIdentityService({
-  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
-  lockout: { maxFailedAttempts: 5, durationSeconds: 900 }
-}, myDatabaseStore);
+const service = createIdentityService(
+  {
+    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
+    lockout: { maxFailedAttempts: 5, durationSeconds: 900 },
+  },
+  myDatabaseStore,
+);
 
 app.use("/auth", createIdentityRouter(service));
 ```
 
 ### Behavioral Gotchas
+
 - **Deny-by-Default**: Principals have no permissions by default. Access must be explicitly granted via roles or direct grants.
 - **Scrypt Password Hashing**: Hashing is computational and synchronous. Avoid calling login in high-throughput loops without caching/throttling.
 - **Refresh Token Rotation**: Refresh tokens are single-use. Re-using an old token immediately revokes all sessions associated with that user.
 
 ## Status
 
-This package is under active implementation. See
-[`specs/009-identity-package`](../../specs/009-identity-package) for the plan and tasks.
+This package is under active implementation.
 
 ## License
 

package/dist/cookie-header-DdTShpuc.d.cts

@@ -0,0 +1,83 @@
+//#region core/cookie-header.d.ts
+/**
+ * Cookie names and Cookie-header parsing for identity sessions.
+ *
+ * Edge-safe: no Node APIs. Use {@link hasIdentityCookies} in Next.js `proxy.ts` /
+ * middleware to gate routes without hitting the database.
+ */
+/** Default HttpOnly cookie that holds the short-lived access JWT. */
+declare const DEFAULT_ACCESS_COOKIE = "azlib_at";
+/** Default HttpOnly cookie that holds the rotating refresh token. */
+declare const DEFAULT_REFRESH_COOKIE = "azlib_rt";
+/** Cookie attribute set shared by access and refresh cookies. */
+interface IdentityCookieAttributes {
+  /** Mark cookies as `HttpOnly`. Default: `true`. */
+  httpOnly?: boolean;
+  /**
+   * Mark cookies as `Secure`. Defaults to `true` when `NODE_ENV` is `"production"`,
+   * `false` otherwise.
+   */
+  secure?: boolean;
+  /** `SameSite` policy. Default: `"lax"`. */
+  sameSite?: "strict" | "lax" | "none";
+  /** Cookie path. Default: `"/"`. */
+  path?: string;
+  /** Cookie domain. Omit to use the current host. */
+  domain?: string;
+}
+/** Names and attributes for the access + refresh cookie pair. */
+interface IdentityCookieOptions extends IdentityCookieAttributes {
+  /** Access-token cookie name. Default: {@link DEFAULT_ACCESS_COOKIE}. */
+  accessCookie?: string;
+  /** Refresh-token cookie name. Default: {@link DEFAULT_REFRESH_COOKIE}. */
+  refreshCookie?: string;
+}
+/** Resolved cookie names. */
+interface IdentityCookieNames {
+  access: string;
+  refresh: string;
+}
+/**
+ * A Next.js `cookies().get` / Request-cookies compatible reader.
+ */
+interface CookieReader {
+  get(name: string): {
+    value: string;
+  } | undefined;
+}
+/**
+ * A Next.js `cookies().set` / `cookies().delete` compatible writer.
+ * `maxAge` is in **seconds** (Web / Next.js convention, not Express milliseconds).
+ */
+interface CookieWriter {
+  set(name: string, value: string, options?: {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date;
+  }): unknown;
+  delete(name: string): unknown;
+}
+type CookieStore = CookieReader & CookieWriter;
+/** Anything {@link hasIdentityCookies} / {@link readCookieValue} can inspect. */
+type CookieSource = CookieReader | Headers | string | null | undefined;
+declare function resolveCookieNames(options?: IdentityCookieOptions): IdentityCookieNames;
+declare function resolveCookieAttributes(options?: IdentityCookieOptions): Required<Pick<IdentityCookieAttributes, "httpOnly" | "sameSite" | "path">> & IdentityCookieAttributes;
+/**
+ * Parses a raw `Cookie` header into a name → value map.
+ * Values are `decodeURIComponent`'d when possible.
+ */
+declare function parseCookieHeader(header: string | null | undefined): Map<string, string>;
+/** Reads a single cookie value from a header string, `Headers`, or cookie reader. */
+declare function readCookieValue(source: CookieSource, name: string): string | undefined;
+/**
+ * Returns true when the request carries an identity access and/or refresh cookie.
+ * Intended for Edge/proxy gates: presence only — do not treat this as authentication.
+ */
+declare function hasIdentityCookies(source: CookieSource, options?: IdentityCookieOptions): boolean;
+//#endregion
+export { DEFAULT_ACCESS_COOKIE as a, IdentityCookieNames as c, parseCookieHeader as d, readCookieValue as f, CookieWriter as i, IdentityCookieOptions as l, resolveCookieNames as m, CookieSource as n, DEFAULT_REFRESH_COOKIE as o, resolveCookieAttributes as p, CookieStore as r, IdentityCookieAttributes as s, CookieReader as t, hasIdentityCookies as u };
+//# sourceMappingURL=cookie-header-DdTShpuc.d.cts.map

package/dist/cookie-header-DdTShpuc.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-header-DdTShpuc.d.cts","names":[],"sources":["../core/cookie-header.ts"],"mappings":";;;;;;;;cAQa;;cAGA;;UAGI;;EAEf;;;;;EAKA;;EAEA;;EAEA;;EAEA;;;UAIe,8BAA8B;;EAE7C;;EAEA;;;UAIe;EACf;EACA;;;;;UAMe;EACf,IAAI;IAAiB;;;;;;;UAON;EACf,IACE,cACA,eACA;IACE;IACA;IACA;IACA;IACA;IACA;IACA,UAAU;;EAGd,OAAO;;KAGG,cAAc,eAAe;;KAG7B,eACR,eACA;iBAKY,mBACd,UAAS,wBACR;iBAOa,wBACd,UAAS,wBACR,SAAS,KAAK,+DACf;;;;;iBAcc,kBACd,oCACC;;iBA8Ba,gBACd,QAAQ,cACR;;;;;iBAqBc,mBACd,QAAQ,cACR,UAAS"}

package/dist/cookie-header-DdTShpuc.d.mts

@@ -0,0 +1,83 @@
+//#region core/cookie-header.d.ts
+/**
+ * Cookie names and Cookie-header parsing for identity sessions.
+ *
+ * Edge-safe: no Node APIs. Use {@link hasIdentityCookies} in Next.js `proxy.ts` /
+ * middleware to gate routes without hitting the database.
+ */
+/** Default HttpOnly cookie that holds the short-lived access JWT. */
+declare const DEFAULT_ACCESS_COOKIE = "azlib_at";
+/** Default HttpOnly cookie that holds the rotating refresh token. */
+declare const DEFAULT_REFRESH_COOKIE = "azlib_rt";
+/** Cookie attribute set shared by access and refresh cookies. */
+interface IdentityCookieAttributes {
+  /** Mark cookies as `HttpOnly`. Default: `true`. */
+  httpOnly?: boolean;
+  /**
+   * Mark cookies as `Secure`. Defaults to `true` when `NODE_ENV` is `"production"`,
+   * `false` otherwise.
+   */
+  secure?: boolean;
+  /** `SameSite` policy. Default: `"lax"`. */
+  sameSite?: "strict" | "lax" | "none";
+  /** Cookie path. Default: `"/"`. */
+  path?: string;
+  /** Cookie domain. Omit to use the current host. */
+  domain?: string;
+}
+/** Names and attributes for the access + refresh cookie pair. */
+interface IdentityCookieOptions extends IdentityCookieAttributes {
+  /** Access-token cookie name. Default: {@link DEFAULT_ACCESS_COOKIE}. */
+  accessCookie?: string;
+  /** Refresh-token cookie name. Default: {@link DEFAULT_REFRESH_COOKIE}. */
+  refreshCookie?: string;
+}
+/** Resolved cookie names. */
+interface IdentityCookieNames {
+  access: string;
+  refresh: string;
+}
+/**
+ * A Next.js `cookies().get` / Request-cookies compatible reader.
+ */
+interface CookieReader {
+  get(name: string): {
+    value: string;
+  } | undefined;
+}
+/**
+ * A Next.js `cookies().set` / `cookies().delete` compatible writer.
+ * `maxAge` is in **seconds** (Web / Next.js convention, not Express milliseconds).
+ */
+interface CookieWriter {
+  set(name: string, value: string, options?: {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date;
+  }): unknown;
+  delete(name: string): unknown;
+}
+type CookieStore = CookieReader & CookieWriter;
+/** Anything {@link hasIdentityCookies} / {@link readCookieValue} can inspect. */
+type CookieSource = CookieReader | Headers | string | null | undefined;
+declare function resolveCookieNames(options?: IdentityCookieOptions): IdentityCookieNames;
+declare function resolveCookieAttributes(options?: IdentityCookieOptions): Required<Pick<IdentityCookieAttributes, "httpOnly" | "sameSite" | "path">> & IdentityCookieAttributes;
+/**
+ * Parses a raw `Cookie` header into a name → value map.
+ * Values are `decodeURIComponent`'d when possible.
+ */
+declare function parseCookieHeader(header: string | null | undefined): Map<string, string>;
+/** Reads a single cookie value from a header string, `Headers`, or cookie reader. */
+declare function readCookieValue(source: CookieSource, name: string): string | undefined;
+/**
+ * Returns true when the request carries an identity access and/or refresh cookie.
+ * Intended for Edge/proxy gates: presence only — do not treat this as authentication.
+ */
+declare function hasIdentityCookies(source: CookieSource, options?: IdentityCookieOptions): boolean;
+//#endregion
+export { DEFAULT_ACCESS_COOKIE as a, IdentityCookieNames as c, parseCookieHeader as d, readCookieValue as f, CookieWriter as i, IdentityCookieOptions as l, resolveCookieNames as m, CookieSource as n, DEFAULT_REFRESH_COOKIE as o, resolveCookieAttributes as p, CookieStore as r, IdentityCookieAttributes as s, CookieReader as t, hasIdentityCookies as u };
+//# sourceMappingURL=cookie-header-DdTShpuc.d.mts.map

package/dist/cookie-header-DdTShpuc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-header-DdTShpuc.d.mts","names":[],"sources":["../core/cookie-header.ts"],"mappings":";;;;;;;;cAQa;;cAGA;;UAGI;;EAEf;;;;;EAKA;;EAEA;;EAEA;;EAEA;;;UAIe,8BAA8B;;EAE7C;;EAEA;;;UAIe;EACf;EACA;;;;;UAMe;EACf,IAAI;IAAiB;;;;;;;UAON;EACf,IACE,cACA,eACA;IACE;IACA;IACA;IACA;IACA;IACA;IACA,UAAU;;EAGd,OAAO;;KAGG,cAAc,eAAe;;KAG7B,eACR,eACA;iBAKY,mBACd,UAAS,wBACR;iBAOa,wBACd,UAAS,wBACR,SAAS,KAAK,+DACf;;;;;iBAcc,kBACd,oCACC;;iBA8Ba,gBACd,QAAQ,cACR;;;;;iBAqBc,mBACd,QAAQ,cACR,UAAS"}

package/dist/cookie-header-DptIxRmW.mjs

@@ -0,0 +1,76 @@
+//#region core/cookie-header.ts
+/**
+* Cookie names and Cookie-header parsing for identity sessions.
+*
+* Edge-safe: no Node APIs. Use {@link hasIdentityCookies} in Next.js `proxy.ts` /
+* middleware to gate routes without hitting the database.
+*/
+/** Default HttpOnly cookie that holds the short-lived access JWT. */
+const DEFAULT_ACCESS_COOKIE = "azlib_at";
+/** Default HttpOnly cookie that holds the rotating refresh token. */
+const DEFAULT_REFRESH_COOKIE = "azlib_rt";
+function resolveCookieNames(options = {}) {
+	return {
+		access: options.accessCookie ?? "azlib_at",
+		refresh: options.refreshCookie ?? "azlib_rt"
+	};
+}
+function resolveCookieAttributes(options = {}) {
+	return {
+		httpOnly: options.httpOnly ?? true,
+		secure: options.secure ?? process.env.NODE_ENV === "production",
+		sameSite: options.sameSite ?? "lax",
+		path: options.path ?? "/",
+		domain: options.domain
+	};
+}
+/**
+* Parses a raw `Cookie` header into a name → value map.
+* Values are `decodeURIComponent`'d when possible.
+*/
+function parseCookieHeader(header) {
+	const result = /* @__PURE__ */ new Map();
+	if (!header) return result;
+	for (const part of header.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		const key = part.slice(0, eq).trim();
+		if (!key) continue;
+		const raw = part.slice(eq + 1).trim();
+		if (result.has(key)) continue;
+		try {
+			result.set(key, decodeURIComponent(raw));
+		} catch {
+			result.set(key, raw);
+		}
+	}
+	return result;
+}
+function isCookieReader(source) {
+	return typeof source === "object" && source !== null && "get" in source && typeof source.get === "function" && !(source instanceof Headers);
+}
+/** Reads a single cookie value from a header string, `Headers`, or cookie reader. */
+function readCookieValue(source, name) {
+	if (source == null) return void 0;
+	if (typeof source === "string") {
+		const value = parseCookieHeader(source).get(name);
+		return value && value.length > 0 ? value : void 0;
+	}
+	if (source instanceof Headers) return readCookieValue(source.get("cookie"), name);
+	if (isCookieReader(source)) {
+		const value = source.get(name)?.value?.trim();
+		return value && value.length > 0 ? value : void 0;
+	}
+}
+/**
+* Returns true when the request carries an identity access and/or refresh cookie.
+* Intended for Edge/proxy gates: presence only — do not treat this as authentication.
+*/
+function hasIdentityCookies(source, options = {}) {
+	const names = resolveCookieNames(options);
+	return readCookieValue(source, names.access) !== void 0 || readCookieValue(source, names.refresh) !== void 0;
+}
+//#endregion
+export { readCookieValue as a, parseCookieHeader as i, DEFAULT_REFRESH_COOKIE as n, resolveCookieAttributes as o, hasIdentityCookies as r, resolveCookieNames as s, DEFAULT_ACCESS_COOKIE as t };
+
+//# sourceMappingURL=cookie-header-DptIxRmW.mjs.map

package/dist/cookie-header-DptIxRmW.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-header-DptIxRmW.mjs","names":[],"sources":["../core/cookie-header.ts"],"sourcesContent":["/**\n * Cookie names and Cookie-header parsing for identity sessions.\n *\n * Edge-safe: no Node APIs. Use {@link hasIdentityCookies} in Next.js `proxy.ts` /\n * middleware to gate routes without hitting the database.\n */\n\n/** Default HttpOnly cookie that holds the short-lived access JWT. */\nexport const DEFAULT_ACCESS_COOKIE = \"azlib_at\";\n\n/** Default HttpOnly cookie that holds the rotating refresh token. */\nexport const DEFAULT_REFRESH_COOKIE = \"azlib_rt\";\n\n/** Cookie attribute set shared by access and refresh cookies. */\nexport interface IdentityCookieAttributes {\n  /** Mark cookies as `HttpOnly`. Default: `true`. */\n  httpOnly?: boolean;\n  /**\n   * Mark cookies as `Secure`. Defaults to `true` when `NODE_ENV` is `\"production\"`,\n   * `false` otherwise.\n   */\n  secure?: boolean;\n  /** `SameSite` policy. Default: `\"lax\"`. */\n  sameSite?: \"strict\" | \"lax\" | \"none\";\n  /** Cookie path. Default: `\"/\"`. */\n  path?: string;\n  /** Cookie domain. Omit to use the current host. */\n  domain?: string;\n}\n\n/** Names and attributes for the access + refresh cookie pair. */\nexport interface IdentityCookieOptions extends IdentityCookieAttributes {\n  /** Access-token cookie name. Default: {@link DEFAULT_ACCESS_COOKIE}. */\n  accessCookie?: string;\n  /** Refresh-token cookie name. Default: {@link DEFAULT_REFRESH_COOKIE}. */\n  refreshCookie?: string;\n}\n\n/** Resolved cookie names. */\nexport interface IdentityCookieNames {\n  access: string;\n  refresh: string;\n}\n\n/**\n * A Next.js `cookies().get` / Request-cookies compatible reader.\n */\nexport interface CookieReader {\n  get(name: string): { value: string } | undefined;\n}\n\n/**\n * A Next.js `cookies().set` / `cookies().delete` compatible writer.\n * `maxAge` is in **seconds** (Web / Next.js convention, not Express milliseconds).\n */\nexport interface CookieWriter {\n  set(\n    name: string,\n    value: string,\n    options?: {\n      httpOnly?: boolean;\n      secure?: boolean;\n      sameSite?: \"strict\" | \"lax\" | \"none\";\n      path?: string;\n      domain?: string;\n      maxAge?: number;\n      expires?: Date;\n    },\n  ): unknown;\n  delete(name: string): unknown;\n}\n\nexport type CookieStore = CookieReader & CookieWriter;\n\n/** Anything {@link hasIdentityCookies} / {@link readCookieValue} can inspect. */\nexport type CookieSource =\n  | CookieReader\n  | Headers\n  | string\n  | null\n  | undefined;\n\nexport function resolveCookieNames(\n  options: IdentityCookieOptions = {},\n): IdentityCookieNames {\n  return {\n    access: options.accessCookie ?? DEFAULT_ACCESS_COOKIE,\n    refresh: options.refreshCookie ?? DEFAULT_REFRESH_COOKIE,\n  };\n}\n\nexport function resolveCookieAttributes(\n  options: IdentityCookieOptions = {},\n): Required<Pick<IdentityCookieAttributes, \"httpOnly\" | \"sameSite\" | \"path\">> &\n  IdentityCookieAttributes {\n  return {\n    httpOnly: options.httpOnly ?? true,\n    secure: options.secure ?? process.env.NODE_ENV === \"production\",\n    sameSite: options.sameSite ?? \"lax\",\n    path: options.path ?? \"/\",\n    domain: options.domain,\n  };\n}\n\n/**\n * Parses a raw `Cookie` header into a name → value map.\n * Values are `decodeURIComponent`'d when possible.\n */\nexport function parseCookieHeader(\n  header: string | null | undefined,\n): Map<string, string> {\n  const result = new Map<string, string>();\n  if (!header) return result;\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq === -1) continue;\n    const key = part.slice(0, eq).trim();\n    if (!key) continue;\n    const raw = part.slice(eq + 1).trim();\n    if (result.has(key)) continue;\n    try {\n      result.set(key, decodeURIComponent(raw));\n    } catch {\n      result.set(key, raw);\n    }\n  }\n  return result;\n}\n\nfunction isCookieReader(source: CookieSource): source is CookieReader {\n  return (\n    typeof source === \"object\" &&\n    source !== null &&\n    \"get\" in source &&\n    typeof source.get === \"function\" &&\n    !(source instanceof Headers)\n  );\n}\n\n/** Reads a single cookie value from a header string, `Headers`, or cookie reader. */\nexport function readCookieValue(\n  source: CookieSource,\n  name: string,\n): string | undefined {\n  if (source == null) return undefined;\n  if (typeof source === \"string\") {\n    const value = parseCookieHeader(source).get(name);\n    return value && value.length > 0 ? value : undefined;\n  }\n  if (source instanceof Headers) {\n    return readCookieValue(source.get(\"cookie\"), name);\n  }\n  if (isCookieReader(source)) {\n    const value = source.get(name)?.value?.trim();\n    return value && value.length > 0 ? value : undefined;\n  }\n  return undefined;\n}\n\n/**\n * Returns true when the request carries an identity access and/or refresh cookie.\n * Intended for Edge/proxy gates: presence only — do not treat this as authentication.\n */\nexport function hasIdentityCookies(\n  source: CookieSource,\n  options: IdentityCookieOptions = {},\n): boolean {\n  const names = resolveCookieNames(options);\n  return (\n    readCookieValue(source, names.access) !== undefined ||\n    readCookieValue(source, names.refresh) !== undefined\n  );\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,wBAAwB;;AAGrC,MAAa,yBAAyB;AAuEtC,SAAgB,mBACd,UAAiC,CAAC,GACb;CACrB,OAAO;EACL,QAAQ,QAAQ,gBAAA;EAChB,SAAS,QAAQ,iBAAA;CACnB;AACF;AAEA,SAAgB,wBACd,UAAiC,CAAC,GAET;CACzB,OAAO;EACL,UAAU,QAAQ,YAAY;EAC9B,QAAQ,QAAQ,UAAU,QAAQ,IAAI,aAAa;EACnD,UAAU,QAAQ,YAAY;EAC9B,MAAM,QAAQ,QAAQ;EACtB,QAAQ,QAAQ;CAClB;AACF;;;;;AAMA,SAAgB,kBACd,QACqB;CACrB,MAAM,yBAAS,IAAI,IAAoB;CACvC,IAAI,CAAC,QAAQ,OAAO;CACpB,KAAK,MAAM,QAAQ,OAAO,MAAM,GAAG,GAAG;EACpC,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,IAAI,OAAO,IAAI;EACf,MAAM,MAAM,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK;EACnC,IAAI,CAAC,KAAK;EACV,MAAM,MAAM,KAAK,MAAM,KAAK,CAAC,CAAC,CAAC,KAAK;EACpC,IAAI,OAAO,IAAI,GAAG,GAAG;EACrB,IAAI;GACF,OAAO,IAAI,KAAK,mBAAmB,GAAG,CAAC;EACzC,QAAQ;GACN,OAAO,IAAI,KAAK,GAAG;EACrB;CACF;CACA,OAAO;AACT;AAEA,SAAS,eAAe,QAA8C;CACpE,OACE,OAAO,WAAW,YAClB,WAAW,QACX,SAAS,UACT,OAAO,OAAO,QAAQ,cACtB,EAAE,kBAAkB;AAExB;;AAGA,SAAgB,gBACd,QACA,MACoB;CACpB,IAAI,UAAU,MAAM,OAAO,KAAA;CAC3B,IAAI,OAAO,WAAW,UAAU;EAC9B,MAAM,QAAQ,kBAAkB,MAAM,CAAC,CAAC,IAAI,IAAI;EAChD,OAAO,SAAS,MAAM,SAAS,IAAI,QAAQ,KAAA;CAC7C;CACA,IAAI,kBAAkB,SACpB,OAAO,gBAAgB,OAAO,IAAI,QAAQ,GAAG,IAAI;CAEnD,IAAI,eAAe,MAAM,GAAG;EAC1B,MAAM,QAAQ,OAAO,IAAI,IAAI,CAAC,EAAE,OAAO,KAAK;EAC5C,OAAO,SAAS,MAAM,SAAS,IAAI,QAAQ,KAAA;CAC7C;AAEF;;;;;AAMA,SAAgB,mBACd,QACA,UAAiC,CAAC,GACzB;CACT,MAAM,QAAQ,mBAAmB,OAAO;CACxC,OACE,gBAAgB,QAAQ,MAAM,MAAM,MAAM,KAAA,KAC1C,gBAAgB,QAAQ,MAAM,OAAO,MAAM,KAAA;AAE/C"}