@bajustone/fortress 1.0.0-rc.1

package/dist/types-et0R8tsC.d.cts

@@ -0,0 +1,217 @@
+/**
+ * A fortress user record as returned by the database adapter.
+ *
+ * `id` is always a string at the fortress API surface. Adapters backed by
+ * numeric primary keys are responsible for stringifying on read and parsing
+ * on write at the adapter boundary — consumers of fortress never see the
+ * underlying representation. This matches the JWT/OIDC `sub` wire shape
+ * (RFC 7519 §4.1.2) and unblocks UUID/ULID/snowflake-keyed adapters.
+ */
+interface FortressUser {
+    id: string;
+    email: string;
+    name: string;
+    isActive: boolean;
+    emailVerified?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** JWT claims fortress signs into the access token, plus the optional impersonation actor (`act`) and per-deployment custom claims. */
+interface TokenClaims {
+    /** Subject identifier — string per RFC 7519 §4.1.2. */
+    sub: string;
+    /** Subject kind — defaults to 'USER' on legacy tokens that do not carry the claim. */
+    subjectType: SubjectType;
+    name: string;
+    groups: string[];
+    iss: string;
+    /** Optional JWT audience, when configured for this deployment. */
+    aud?: string | string[];
+    iat: number;
+    exp: number;
+    act?: {
+        sub: string;
+        subjectType?: SubjectType;
+    };
+    customClaims?: Record<string, unknown>;
+}
+/** A short-lived access token paired with its longer-lived refresh token. */
+interface AuthTokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+/** The credential method that completed authentication. Carried on a successful result. */
+type AuthMethod = 'password' | 'refresh' | 'two-factor' | 'webauthn' | 'magic-link' | 'impersonation';
+/** Why a sign-in is pending an additional step before tokens are issued. */
+type PendingReason = 'two-factor' | 'webauthn' | 'email-verification' | 'magic-link';
+/**
+ * The challenge a pending sign-in must satisfy before tokens are issued.
+ * `reason` tells the client which step to run; the single-use `continuationToken`
+ * is presented back to `auth.completePendingAuth` to finish the flow.
+ */
+interface AuthChallenge {
+    reason: PendingReason;
+    continuationToken: string;
+}
+/** Successful sign-in / refresh result — both tokens are issued. */
+interface AuthSuccess {
+    status: 'success';
+    user: FortressUser;
+    method: AuthMethod;
+    accessToken: string;
+    refreshToken: string;
+    pluginData?: Record<string, unknown>;
+}
+/** Impersonation sign-in result — only an access token is issued (refresh is suppressed for safety). */
+interface AuthImpersonation {
+    status: 'impersonation';
+    user: FortressUser;
+    accessToken: string;
+    refreshToken: null;
+    pluginData?: Record<string, unknown>;
+}
+/** Pending sign-in result — the user must complete an additional step before tokens are issued. */
+interface AuthPending {
+    status: 'pending';
+    user: FortressUser;
+    pending: AuthChallenge;
+    pluginData?: Record<string, unknown>;
+}
+/** Discriminated union of every possible auth flow outcome. */
+type AuthResult = AuthSuccess | AuthImpersonation | AuthPending;
+/** Narrow an {@link AuthResult} to the successful (tokens-issued) variant. */
+declare function isSuccess(result: AuthResult): result is AuthSuccess;
+/** Narrow an {@link AuthResult} to the pending (additional-step-required) variant. */
+declare function isPending(result: AuthResult): result is AuthPending;
+/** Narrow an {@link AuthResult} to the impersonation variant. */
+declare function isImpersonation(result: AuthResult): result is AuthImpersonation;
+/**
+ * Assert an {@link AuthResult} is successful, throwing otherwise. Use when a
+ * caller has already ruled out the pending/impersonation variants and wants the
+ * token fields without a manual narrow.
+ */
+declare function assertSuccess(result: AuthResult): asserts result is AuthSuccess;
+/** Per-request metadata fortress threads through hooks for audit logging, lockout, and trusted-device tracking. */
+interface RequestMeta {
+    ipAddress?: string;
+    userAgent?: string;
+    deviceName?: string;
+    /** Raw server-issued trusted-device secret from the host-owned cookie. */
+    trustedDeviceToken?: string;
+    /** Explicitly request enrollment of this browser/device after a successful factor. */
+    rememberDevice?: boolean;
+}
+/** A persisted refresh-token session as exposed to session-management UIs. */
+interface SessionInfo {
+    id: string;
+    ipAddress: string | null;
+    userAgent: string | null;
+    deviceName: string | null;
+    createdAt: Date;
+    lastActiveAt: Date | null;
+}
+/** Input shape accepted by `fortress.createUser` and the admin user-creation endpoint. */
+interface CreateUserInput {
+    email: string;
+    name: string;
+    password?: string;
+    isActive?: boolean;
+}
+/** The kind of subject a role or permission can be bound to. */
+type SubjectType = 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+/** A subject identity — a discriminated (type, id) pair used by IAM and the auth pipeline. */
+interface Subject {
+    type: SubjectType;
+    id: string;
+}
+/** A persisted IAM permission — a (resource, action) pair with optional conditions and an allow/deny effect. */
+interface Permission {
+    id: string;
+    resource: string;
+    action: string;
+    effect: 'ALLOW' | 'DENY';
+    conditions?: PermissionCondition[];
+    description?: string;
+}
+/** Input shape for creating a new {@link Permission}. */
+interface PermissionInput {
+    resource: string;
+    action: string;
+    effect?: 'ALLOW' | 'DENY';
+    conditions?: PermissionCondition[];
+}
+/** Reference to a value resolved from the {@link PermissionContext} at evaluation time. */
+interface ConditionRef {
+    ref: string;
+}
+/** A literal or {@link ConditionRef}-based value used by a {@link PermissionCondition}. */
+type ConditionValue = string | string[] | ConditionRef | ConditionRef[];
+/** A single ABAC-style condition guarding a {@link Permission}. */
+interface PermissionCondition {
+    field: string;
+    operator: 'eq' | 'neq' | 'in' | 'startsWith';
+    value: ConditionValue;
+}
+/** Context object passed into the permission evaluator at check time. */
+interface PermissionContext {
+    resource?: Record<string, unknown>;
+    request?: Record<string, unknown>;
+    user?: Record<string, unknown>;
+    tenantId?: string;
+    /**
+     * Optional narrowing scopes from the credential used for this request
+     * (for example an API key). `null`/`undefined` means unscoped/full
+     * subject permissions; an empty array means no permissions.
+     */
+    credentialScopes?: string[] | null;
+}
+/** A persisted IAM role grouping a set of {@link Permission}s. */
+interface Role {
+    id: string;
+    name: string;
+    description?: string | null;
+    isSystem?: boolean;
+}
+/** Binding of a {@link Role} to a subject (user, group, or service account), optionally scoped to a tenant. */
+interface RoleBinding {
+    id: string;
+    roleId: string;
+    subjectType: SubjectType;
+    subjectId: string;
+    tenantId?: string | null;
+}
+/** The kind of identifier a user can sign in with. */
+type LoginIdentifierType = 'email' | 'phone' | 'username';
+/** A persisted login identifier (e.g. email, phone, username) attached to a user. */
+interface LoginIdentifier {
+    id: string;
+    userId: string;
+    type: LoginIdentifierType;
+    value: string;
+    /** Reserved for future multi-tenant support. Not yet stored in the database. */
+    tenantId?: string | null;
+}
+/** A persisted IAM group used to grant permissions to many users at once. */
+interface Group {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** A persisted IAM service account — a non-human principal that can hold roles and direct permissions. */
+interface ServiceAccount {
+    id: string;
+    name: string;
+    displayName: string | null;
+    description: string | null;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input shape for creating a new {@link ServiceAccount}. `name` is the immutable machine identifier. */
+interface CreateServiceAccountInput {
+    name: string;
+    displayName?: string;
+    description?: string;
+}
+
+export { type AuthResult as A, type CreateServiceAccountInput as C, type FortressUser as F, type Group as G, type LoginIdentifierType as L, type PermissionContext as P, type RequestMeta as R, type Subject as S, type TokenClaims as T, type SubjectType as a, type Permission as b, type PermissionInput as c, type Role as d, type RoleBinding as e, type ServiceAccount as f, type AuthMethod as g, type AuthTokenPair as h, type CreateUserInput as i, type SessionInfo as j, type LoginIdentifier as k, type PendingReason as l, type AuthChallenge as m, type AuthImpersonation as n, type AuthPending as o, type AuthSuccess as p, type ConditionRef as q, type ConditionValue as r, type PermissionCondition as s, assertSuccess as t, isImpersonation as u, isPending as v, isSuccess as w };

package/dist/types-et0R8tsC.d.ts

@@ -0,0 +1,217 @@
+/**
+ * A fortress user record as returned by the database adapter.
+ *
+ * `id` is always a string at the fortress API surface. Adapters backed by
+ * numeric primary keys are responsible for stringifying on read and parsing
+ * on write at the adapter boundary — consumers of fortress never see the
+ * underlying representation. This matches the JWT/OIDC `sub` wire shape
+ * (RFC 7519 §4.1.2) and unblocks UUID/ULID/snowflake-keyed adapters.
+ */
+interface FortressUser {
+    id: string;
+    email: string;
+    name: string;
+    isActive: boolean;
+    emailVerified?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** JWT claims fortress signs into the access token, plus the optional impersonation actor (`act`) and per-deployment custom claims. */
+interface TokenClaims {
+    /** Subject identifier — string per RFC 7519 §4.1.2. */
+    sub: string;
+    /** Subject kind — defaults to 'USER' on legacy tokens that do not carry the claim. */
+    subjectType: SubjectType;
+    name: string;
+    groups: string[];
+    iss: string;
+    /** Optional JWT audience, when configured for this deployment. */
+    aud?: string | string[];
+    iat: number;
+    exp: number;
+    act?: {
+        sub: string;
+        subjectType?: SubjectType;
+    };
+    customClaims?: Record<string, unknown>;
+}
+/** A short-lived access token paired with its longer-lived refresh token. */
+interface AuthTokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+/** The credential method that completed authentication. Carried on a successful result. */
+type AuthMethod = 'password' | 'refresh' | 'two-factor' | 'webauthn' | 'magic-link' | 'impersonation';
+/** Why a sign-in is pending an additional step before tokens are issued. */
+type PendingReason = 'two-factor' | 'webauthn' | 'email-verification' | 'magic-link';
+/**
+ * The challenge a pending sign-in must satisfy before tokens are issued.
+ * `reason` tells the client which step to run; the single-use `continuationToken`
+ * is presented back to `auth.completePendingAuth` to finish the flow.
+ */
+interface AuthChallenge {
+    reason: PendingReason;
+    continuationToken: string;
+}
+/** Successful sign-in / refresh result — both tokens are issued. */
+interface AuthSuccess {
+    status: 'success';
+    user: FortressUser;
+    method: AuthMethod;
+    accessToken: string;
+    refreshToken: string;
+    pluginData?: Record<string, unknown>;
+}
+/** Impersonation sign-in result — only an access token is issued (refresh is suppressed for safety). */
+interface AuthImpersonation {
+    status: 'impersonation';
+    user: FortressUser;
+    accessToken: string;
+    refreshToken: null;
+    pluginData?: Record<string, unknown>;
+}
+/** Pending sign-in result — the user must complete an additional step before tokens are issued. */
+interface AuthPending {
+    status: 'pending';
+    user: FortressUser;
+    pending: AuthChallenge;
+    pluginData?: Record<string, unknown>;
+}
+/** Discriminated union of every possible auth flow outcome. */
+type AuthResult = AuthSuccess | AuthImpersonation | AuthPending;
+/** Narrow an {@link AuthResult} to the successful (tokens-issued) variant. */
+declare function isSuccess(result: AuthResult): result is AuthSuccess;
+/** Narrow an {@link AuthResult} to the pending (additional-step-required) variant. */
+declare function isPending(result: AuthResult): result is AuthPending;
+/** Narrow an {@link AuthResult} to the impersonation variant. */
+declare function isImpersonation(result: AuthResult): result is AuthImpersonation;
+/**
+ * Assert an {@link AuthResult} is successful, throwing otherwise. Use when a
+ * caller has already ruled out the pending/impersonation variants and wants the
+ * token fields without a manual narrow.
+ */
+declare function assertSuccess(result: AuthResult): asserts result is AuthSuccess;
+/** Per-request metadata fortress threads through hooks for audit logging, lockout, and trusted-device tracking. */
+interface RequestMeta {
+    ipAddress?: string;
+    userAgent?: string;
+    deviceName?: string;
+    /** Raw server-issued trusted-device secret from the host-owned cookie. */
+    trustedDeviceToken?: string;
+    /** Explicitly request enrollment of this browser/device after a successful factor. */
+    rememberDevice?: boolean;
+}
+/** A persisted refresh-token session as exposed to session-management UIs. */
+interface SessionInfo {
+    id: string;
+    ipAddress: string | null;
+    userAgent: string | null;
+    deviceName: string | null;
+    createdAt: Date;
+    lastActiveAt: Date | null;
+}
+/** Input shape accepted by `fortress.createUser` and the admin user-creation endpoint. */
+interface CreateUserInput {
+    email: string;
+    name: string;
+    password?: string;
+    isActive?: boolean;
+}
+/** The kind of subject a role or permission can be bound to. */
+type SubjectType = 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+/** A subject identity — a discriminated (type, id) pair used by IAM and the auth pipeline. */
+interface Subject {
+    type: SubjectType;
+    id: string;
+}
+/** A persisted IAM permission — a (resource, action) pair with optional conditions and an allow/deny effect. */
+interface Permission {
+    id: string;
+    resource: string;
+    action: string;
+    effect: 'ALLOW' | 'DENY';
+    conditions?: PermissionCondition[];
+    description?: string;
+}
+/** Input shape for creating a new {@link Permission}. */
+interface PermissionInput {
+    resource: string;
+    action: string;
+    effect?: 'ALLOW' | 'DENY';
+    conditions?: PermissionCondition[];
+}
+/** Reference to a value resolved from the {@link PermissionContext} at evaluation time. */
+interface ConditionRef {
+    ref: string;
+}
+/** A literal or {@link ConditionRef}-based value used by a {@link PermissionCondition}. */
+type ConditionValue = string | string[] | ConditionRef | ConditionRef[];
+/** A single ABAC-style condition guarding a {@link Permission}. */
+interface PermissionCondition {
+    field: string;
+    operator: 'eq' | 'neq' | 'in' | 'startsWith';
+    value: ConditionValue;
+}
+/** Context object passed into the permission evaluator at check time. */
+interface PermissionContext {
+    resource?: Record<string, unknown>;
+    request?: Record<string, unknown>;
+    user?: Record<string, unknown>;
+    tenantId?: string;
+    /**
+     * Optional narrowing scopes from the credential used for this request
+     * (for example an API key). `null`/`undefined` means unscoped/full
+     * subject permissions; an empty array means no permissions.
+     */
+    credentialScopes?: string[] | null;
+}
+/** A persisted IAM role grouping a set of {@link Permission}s. */
+interface Role {
+    id: string;
+    name: string;
+    description?: string | null;
+    isSystem?: boolean;
+}
+/** Binding of a {@link Role} to a subject (user, group, or service account), optionally scoped to a tenant. */
+interface RoleBinding {
+    id: string;
+    roleId: string;
+    subjectType: SubjectType;
+    subjectId: string;
+    tenantId?: string | null;
+}
+/** The kind of identifier a user can sign in with. */
+type LoginIdentifierType = 'email' | 'phone' | 'username';
+/** A persisted login identifier (e.g. email, phone, username) attached to a user. */
+interface LoginIdentifier {
+    id: string;
+    userId: string;
+    type: LoginIdentifierType;
+    value: string;
+    /** Reserved for future multi-tenant support. Not yet stored in the database. */
+    tenantId?: string | null;
+}
+/** A persisted IAM group used to grant permissions to many users at once. */
+interface Group {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** A persisted IAM service account — a non-human principal that can hold roles and direct permissions. */
+interface ServiceAccount {
+    id: string;
+    name: string;
+    displayName: string | null;
+    description: string | null;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input shape for creating a new {@link ServiceAccount}. `name` is the immutable machine identifier. */
+interface CreateServiceAccountInput {
+    name: string;
+    displayName?: string;
+    description?: string;
+}
+
+export { type AuthResult as A, type CreateServiceAccountInput as C, type FortressUser as F, type Group as G, type LoginIdentifierType as L, type PermissionContext as P, type RequestMeta as R, type Subject as S, type TokenClaims as T, type SubjectType as a, type Permission as b, type PermissionInput as c, type Role as d, type RoleBinding as e, type ServiceAccount as f, type AuthMethod as g, type AuthTokenPair as h, type CreateUserInput as i, type SessionInfo as j, type LoginIdentifier as k, type PendingReason as l, type AuthChallenge as m, type AuthImpersonation as n, type AuthPending as o, type AuthSuccess as p, type ConditionRef as q, type ConditionValue as r, type PermissionCondition as s, assertSuccess as t, isImpersonation as u, isPending as v, isSuccess as w };

package/docs/adapter-typed-helpers.md

@@ -0,0 +1,192 @@
+# Typed adapter helpers
+
+Fortress's framework adapters (Hono, Express, SvelteKit) attach
+request-scoped state (`fortressSubject`, `fortressUserId`,
+`fortressClaims`, `fortressDb`, `fortressGetScopedDb`,
+`fortressScopes`). This page covers how to read that state from your own
+handlers with **no casts**, while keeping your own env/locals/request
+augmentations intact.
+
+The plugin-method surface (`fortress.plugins.<name>.method(...)`) is
+already typed via `InferPlugins<T>` — the const generic plugin list
+passed to `createFortress` carries each plugin's method-shape through to
+`fortress.plugins`. Nothing extra to do.
+
+---
+
+## Hono — `FortressEnv<TAppEnv>`
+
+The Hono adapter exports a generic env type that composes your own
+`Variables` and `Bindings` with Fortress's. Use the default
+`FortressEnv` for Fortress-only apps; parameterize it with your env for
+apps that already declare their own variables.
+
+```ts
+import { Hono } from 'hono';
+import {
+  FortressEnv,
+  createHonoMiddleware,
+  getClaims,
+  getSubject,
+  getUserId,
+} from '@bajustone/fortress/hono';
+
+interface MyEnv {
+  Variables: { requestId: string };
+  Bindings: { DB: D1Database };
+}
+
+const app = new Hono<FortressEnv<MyEnv>>();
+const { authMiddleware, errorHandler } = createHonoMiddleware(fortress);
+app.use(authMiddleware);
+app.onError(errorHandler);
+
+app.get('/me', (c) => {
+  const requestId = c.get('requestId');  // string  (host-defined)
+  const subject = getSubject(c);          // Subject (fortress-defined)
+  const userId = getUserId(c);            // string  (USER-only)
+  return c.json({ requestId, subject, userId });
+});
+```
+
+### Typed custom JWT claims
+
+`getClaims<TCustomClaims>(c)` narrows the `customClaims` slot to your
+deployment's plugin-augmented shape. The tenancy plugin, for example,
+adds `tenantId` / `tenantCode`:
+
+```ts
+interface MyClaims {
+  tenantId: string;
+  tenantCode: string;
+}
+
+app.get('/iam/whoami', (c) => {
+  const claims = getClaims<MyClaims>(c);
+  const tenantCode = claims.customClaims?.tenantCode; // string | undefined
+  return c.json({ sub: claims.sub, tenantCode });
+});
+```
+
+### Exports
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `FortressEnv<TAppEnv>` | type | Generic env composing your env with Fortress's variables |
+| `FortressVariables` | type | The bare Fortress `Variables` slot — useful for `Hono<{ Variables: FortressVariables & MyVars }>` |
+| `FortressContext<E>` | type | Sugar for `Context<E>` typed handlers |
+| `getSubject<E>(c)` | function | Returns `Subject`; throws 401 if unauthenticated |
+| `getUserId<E>(c)` | function | Returns `string`; throws 401 if subject is not a `USER` |
+| `getClaims<T, E>(c)` | function | Returns `TokenClaims & { customClaims?: T }` |
+| `getDb<E>(c)` | function | Per-request `DatabaseAdapter` with plugin `wrapAdapter` applied |
+| `getScopedDb<E>(c, model)` | function | Adds `scopeRules` for `model` on top of `getDb` |
+
+All helpers are generic in the env type so they accept any
+`Context<E>` whose `Variables` include `FortressVariables`.
+
+---
+
+## Express — `FortressExpressFields`
+
+The Express adapter exports the Fortress-specific fields it attaches to
+the `Request` object so you can **declaration-merge** them into express's
+native `Request` type. Once merged, your route handlers see the typed
+fields with no casts.
+
+```ts
+// src/types/express.d.ts
+import type { FortressExpressFields } from '@bajustone/fortress/express';
+
+declare module 'express-serve-static-core' {
+  interface Request extends FortressExpressFields {}
+}
+```
+
+```ts
+// src/routes/me.ts
+import { Router } from 'express';
+import { createAuthMiddleware } from '@bajustone/fortress/express';
+
+const router = Router();
+router.use(createAuthMiddleware(fortress));
+
+router.get('/me', (req, res) => {
+  const subject = req.fortressSubject;       // Subject | undefined  (typed)
+  const userId = req.fortressUserId;          // string   | undefined
+  const claims = req.fortressClaims;          // TokenClaims | undefined
+  res.json({ subject, userId, claims });
+});
+```
+
+`@bajustone/fortress/express` also exports the helper functions
+(`getSubject(req)`, `getUserId(req)`, `getClaims(req)`, `getDb(req)`,
+`getScopedDb(req, model)`) — they're equivalent to reading the fields
+directly, but throw a typed 401 when the field is missing instead of
+returning `undefined`.
+
+---
+
+## SvelteKit — `FortressLocals`
+
+The SvelteKit adapter exposes `event.locals.fortress` (subject, userId,
+claims, scopes, db, getScopedDb). Augment SvelteKit's `App.Locals` once
+and your `+server.ts` / `+page.server.ts` handlers see the typed shape
+everywhere.
+
+```ts
+// src/app.d.ts
+import type { FortressLocals } from '@bajustone/fortress/sveltekit';
+
+declare global {
+  namespace App {
+    interface Locals extends FortressLocals {}
+  }
+}
+```
+
+```ts
+// src/routes/api/me/+server.ts
+import { json } from '@sveltejs/kit';
+import { getSubject } from '@bajustone/fortress/sveltekit';
+
+export const GET = ({ locals }) => {
+  const subject = locals.fortress?.subject;  // Subject | undefined  (typed)
+  return json({ subject });
+};
+```
+
+`FortressLocals` already extends Fortress's variables under the
+`fortress` key, so multiple library augmentations of `App.Locals` (e.g.
+your own session library + Fortress) coexist without colliding.
+
+---
+
+## Typed plugin methods
+
+`fortress.plugins.<name>` is automatically typed from the plugin's
+`methods` return type, propagated through the const generic plugin
+list:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { tenancy } from '@bajustone/fortress/plugins/tenancy';
+import { apiKey } from '@bajustone/fortress/plugins/api-key';
+
+const fortress = createFortress({
+  database: db,
+  jwt: { key: secret },
+  plugins: [tenancy(), apiKey({ prefix: 'fortress' })] as const,
+});
+
+// All typed; no casts.
+await fortress.plugins.tenancy.createTenant({ name: 'Acme', taxId: 'acme-001' });
+await fortress.plugins['api-key'].createKey({
+  subject: { type: 'USER', id: userId },
+  name: 'CI',
+  scopes: ['*'],
+});
+```
+
+For dynamic plugin lookup (e.g. a plugin loaded by name at runtime),
+use `getPluginMethods<T>(fortress, name)` to attach a known interface
+without casting.