@manablox/auth 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+import { ALL_PERMISSIONS, AuditActor, AuthConfig, BUILT_IN_ROLES, BuiltInRole, CONTENT_ACTIONS, ContentAction, ContentPermission, ContentPermission as ContentPermission$1, Grant, Manablox, PERMISSION_GROUPS, Permission, Permission as Permission$1, PermissionGroup, SpaceRole, SpaceRole as SpaceRole$1, grantsCover, intersectGrants, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, typesCoveredBy } from "@manablox/core";
+import { Database, MembershipRow, Repositories, SpaceRow } from "@manablox/db";
+//#region src/rbac.d.ts
+export interface Principal {
+  userId: string;
+  email: string;
+  /** Instance-wide role; `superadmin` short-circuits every space check. */
+  role: string;
+  /** Space id → the name of the role held there. */
+  spaces: Record<string, SpaceRole$1>;
+  /**
+   * Space id → the grants that role carries, resolved when the principal is. Absent for
+   * a space whose role is built in: those are answered from the table above.
+   */
+  permissions?: Record<string, readonly string[]>;
+  /** True when the request authenticated with an API key rather than a session. */
+  viaApiKey?: boolean;
+  /** The key that authenticated the request, for the audit log. */
+  apiKeyId?: string | null;
+  apiKeyName?: string | null;
+  /**
+   * Spaces this principal is confined to, or `null`/absent for no confinement. Set by an
+   * API key that was issued with a space restriction: it narrows the key below its
+   * owner's own access and, unlike a role, it also binds a superadmin.
+   */
+  allowedSpaceIds?: string[] | null;
+  /**
+   * Grants this principal is confined to, or `null`/absent for no confinement. Set by an
+   * API key issued with a permission restriction: like `allowedSpaceIds` it only ever
+   * narrows the owner's own access, and it binds a superadmin too.
+   */
+  allowedGrants?: readonly string[] | null;
+}
+/**
+ * The principal as the audit log records it: a user, or a user through an API key, with
+ * the request's client details beside it. Anonymous requests act as the system.
+ */
+export declare function auditActorFor(principal: Principal | null, request?: {
+  headers: Headers;
+  requestId?: string | null | undefined;
+}): AuditActor;
+/** The grants a principal's role gives in a space, whatever kind of role it is. */
+export declare function grantsIn(principal: Principal, spaceId: string): readonly string[];
+/**
+ * What a principal can actually do in a space: the role's grants (everything, for a
+ * superadmin) narrowed by an API key's restriction, if the request came through one.
+ */
+export declare function effectiveGrants(principal: Principal, spaceId: string): readonly string[];
+export declare function can(principal: Principal | null, spaceId: string | null, permission: Permission$1, typeId?: string | null): boolean;
+export declare function assertCan(principal: Principal | null, spaceId: string | null, permission: Permission$1, typeId?: string | null): void;
+/**
+ * The content types a principal may perform an action on in a space, or `null` for
+ * every type — what a listing narrows its filter to.
+ */
+export declare function allowedTypeIds(principal: Principal | null, spaceId: string, permission: ContentPermission$1): string[] | null;
+/** Roles used by field-level `readRoles`/`writeRoles` checks. */
+export declare function actorRoles(principal: Principal | null, spaceId: string | null): string[];
+//#endregion
+//#region src/api-key.d.ts
+export interface IssuedApiKey {
+  id: string;
+  name: string;
+  /** The full secret, shown once at creation and never recoverable afterwards. */
+  key: string;
+  prefix: string;
+}
+export interface IssueApiKeyOptions {
+  expiresAt?: Date | undefined;
+  /** Spaces the key may act in. `null`/omitted issues an unrestricted key. */
+  spaceIds?: string[] | null | undefined;
+  /** Grants the key may use. `null`/omitted leaves the owner's role as the limit. */
+  permissions?: string[] | null | undefined;
+}
+/**
+ * Takes a presented key apart. The secret is base64url and may itself contain `_`, so
+ * the key is not split on it: the prefix is a fixed twelve hex characters and the
+ * secret is whatever follows.
+ */
+export declare function parseApiKey(presented: string): {
+  prefix: string;
+  secret: string;
+} | null;
+/**
+ * Long-lived credentials for headless consumers.
+ *
+ * Keys are stored as a SHA-256 digest, never in plaintext, and are looked up by an
+ * indexed non-secret prefix so verification is one indexed read plus one constant-time
+ * comparison — not a scan-and-compare over every row.
+ */
+export declare class ApiKeyService {
+  private readonly db;
+  private readonly repos;
+  constructor(db: Database, repos: Repositories);
+  issue(userId: string, name: string, options?: IssueApiKeyOptions): Promise<IssuedApiKey>;
+  /**
+   * Deletes the row rather than clearing `enabled`: a revoked key is never listed again
+   * or re-enabled, so a disabled row is only a secret digest left lying around.
+   */
+  revoke(id: string): Promise<void>;
+  list(userId: string): Promise<{
+    id: string;
+    name: string | null;
+    start: string | null;
+    enabled: boolean;
+    expiresAt: Date | null;
+    lastRequest: Date | null;
+    spaceIds: string[] | null;
+    permissions: string[] | null;
+    createdAt: Date;
+  }[]>;
+  resolve(presented: string): Promise<Principal | null>;
+  /** Removes expired keys; scheduled by the jobs package. */
+  pruneExpired(): Promise<number>;
+}
+//#endregion
+//#region src/password.d.ts
+/**
+ * Argon2id, the current OWASP recommendation over bcrypt — which also silently truncates
+ * passwords at 72 bytes. One definition serves better-auth's own sign-in path and the
+ * accounts an administrator creates, so both write the same hash format.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(stored: string, password: string): Promise<boolean>;
+/** Matches better-auth's `minPasswordLength`, so a password set here signs in there. */
+export declare const MIN_PASSWORD_LENGTH = 12;
+//#endregion
+//#region src/user.service.d.ts
+export type InstanceRole = 'superadmin' | 'editor';
+export interface CreateUserInput {
+  name: string;
+  email: string;
+  password: string;
+  role: InstanceRole;
+}
+export interface UpdateUserInput {
+  name?: string | undefined;
+  email?: string | undefined;
+}
+/** A user row without anything a directory listing should not carry. */
+export interface UserSummary {
+  id: string;
+  name: string;
+  email: string;
+  image: string | null;
+  role: string;
+  banned: boolean;
+  banReason: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+export interface UserDetail extends UserSummary {
+  memberships: Array<{
+    spaceId: string;
+    role: MembershipRow['role'];
+    space: SpaceRow;
+  }>;
+}
+/**
+ * Instance-wide user administration: the accounts, their instance role, and whether they
+ * may sign in at all. Space membership stays with `SpaceService`, because it is a
+ * property of the space.
+ *
+ * Every rule here exists to keep the instance reachable: an administrator cannot lock
+ * themself out, and the instance always keeps at least one superadmin.
+ */
+export declare class UserService {
+  private readonly repos;
+  constructor(repos: Repositories);
+  get(userId: string): Promise<UserDetail>;
+  list(pagination: {
+    limit: number;
+    offset: number;
+  }, search?: string): Promise<{
+    total: number;
+    limit: number;
+    offset: number;
+    items: UserSummary[];
+  }>;
+  create(input: CreateUserInput): Promise<UserSummary>;
+  update(userId: string, input: UpdateUserInput): Promise<UserSummary>;
+  /** Changing the instance role; the last superadmin cannot step down. */
+  setRole(userId: string, role: InstanceRole): Promise<UserSummary>;
+  /**
+   * A new password, and every session gone with the old one: whoever held the account
+   * before the reset does not keep it afterwards.
+   */
+  setPassword(userId: string, password: string): Promise<void>;
+  /**
+   * The account holder changing their own password: the current one must be right, and
+   * unlike an administrator's reset the other sessions stay signed in, since the person
+   * holding the account is the one making the change.
+   */
+  changePassword(userId: string, currentPassword: string, password: string): Promise<void>;
+  /** A banned user is signed out everywhere and refused on the next request. */
+  ban(actorId: string, userId: string, reason: string | null): Promise<UserSummary>;
+  unban(userId: string): Promise<UserSummary>;
+  delete(actorId: string, userId: string): Promise<void>;
+  /** Signs the user out of every device without touching the account. */
+  revokeSessions(userId: string): Promise<void>;
+  /** Accounts are instance-wide, so their entries carry no space. */
+  private audit;
+  private require;
+  private assertNotSelf;
+  /**
+   * Whatever happens to `userId`, one superadmin must remain — otherwise the instance
+   * has no one left who can create a space or manage users, and no way back.
+   */
+  private assertNotLastSuperadmin;
+}
+//#endregion
+//#region src/index.d.ts
+export type ManabloxAuth = ReturnType<typeof createAuth>;
+/** better-auth, wired to the Drizzle schema. Sessions are rows, so concurrent devices
+ * each hold their own. */
+export interface AuthCallbacks {
+  /** Runs after a user row is created, inside better-auth's own transaction path. */
+  onUserCreated?: (userId: string) => Promise<void>;
+  /**
+   * Whether the public sign-up endpoint may create an account right now. Absent means
+   * always. The host closes it once the first account exists, so every later account is
+   * created by an administrator rather than by whoever finds the login page.
+   */
+  allowSignUp?: () => Promise<boolean>;
+  /** Runs after a session row is created: a sign-in. */
+  onSessionCreated?: (session: {
+    userId: string;
+    ipAddress?: string | null | undefined;
+    userAgent?: string | null | undefined;
+  }) => Promise<void>;
+}
+export declare function createAuth(config: AuthConfig, db: Database, callbacks?: AuthCallbacks): import("better-auth").Auth<{
+  secret: string;
+  baseURL?: string;
+  trustedOrigins: string[];
+  database: (options: import("better-auth").BetterAuthOptions) => import("better-auth").DBAdapter<import("better-auth").BetterAuthOptions>;
+  emailAndPassword: {
+    enabled: boolean;
+    minPasswordLength: number;
+    password: {
+      hash: typeof hashPassword;
+      verify: ({ hash: stored, password }: {
+        hash: string;
+        password: string;
+      }) => Promise<boolean>;
+    };
+  };
+  session: {
+    expiresIn: number;
+    updateAge: number;
+    cookieCache: {
+      enabled: true;
+      maxAge: number;
+    };
+  };
+  plugins: [{
+    id: "bearer";
+    version: string;
+    hooks: {
+      before: {
+        matcher(context: import("better-auth").HookEndpointContext): boolean;
+        handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+          context: {
+            headers: Headers;
+          };
+        } | undefined>>;
+      }[];
+      after: {
+        matcher(context: import("better-auth").HookEndpointContext): true;
+        handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+      }[];
+    };
+    options: import("better-auth/plugins").BearerOptions | undefined;
+  }];
+  databaseHooks: {
+    user: {
+      create: {
+        before: (user: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          email: string;
+          emailVerified: boolean;
+          name: string;
+          image?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<{
+          data: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            email: string;
+            emailVerified: boolean;
+            name: string;
+            image?: string | null | undefined;
+          } & Record<string, unknown>;
+        }>;
+        after: (user: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          email: string;
+          emailVerified: boolean;
+          name: string;
+          image?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<void>;
+      };
+    };
+    session: {
+      create: {
+        after: (session: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          userId: string;
+          expiresAt: Date;
+          token: string;
+          ipAddress?: string | null | undefined;
+          userAgent?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<void>;
+      };
+    };
+  };
+  advanced: {
+    database: {
+      generateId: () => `${string}-${string}-${string}-${string}-${string}`;
+    };
+  };
+}>;
+/**
+ * Resolves a request's session into a `Principal`, including its space memberships.
+ * Returns `null` for anonymous requests rather than throwing — route guards decide.
+ */
+export declare function resolvePrincipal(auth: ManabloxAuth, repos: Repositories, headers: Headers, apiKeys?: ApiKeyService): Promise<Principal | null>;
+/**
+ * Promotes the very first account to `superadmin` and grants it ownership of every
+ * existing space, so a fresh install is reachable.
+ *
+ * Called from better-auth's user-create hook rather than at startup, so it fires for an
+ * account created after the server is already running.
+ */
+export declare function promoteFirstUser(manablox: Manablox, repos: Repositories, userId: string): Promise<void>;
+/** Covers an instance whose first account predates this behaviour. */
+export declare function attachBootstrapOwner(manablox: Manablox, repos: Repositories): void;
+//#endregion
+export { ALL_PERMISSIONS, BUILT_IN_ROLES, type BuiltInRole, CONTENT_ACTIONS, type ContentAction, type ContentPermission, type Grant, PERMISSION_GROUPS, type Permission, type PermissionGroup, type SpaceRole, grantsCover, intersectGrants, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, typesCoveredBy };