auth/account_schema.ts

Auth entity types and client-safe schemas.

Defines the runtime types for the fuz identity system: Account, Actor, RoleGrant, AuthSession, and ApiToken.

Identifier primitives (Username, UsernameProvided, Email) live in ../primitive_schemas.ts — they're general validator shapes that don't depend on the auth domain. The auth-shape request-contract primitive ActingActor lives in ../http/auth_shape.ts next to RouteAuth (the two pair: auth.actor !== 'none' ⟺ input declares acting?: ActingActor).

DDL lives in auth/auth_ddl.ts; role system in auth/role_schema.ts. See docs/identity.md for design rationale.

Declarations
#

20 declarations

view source

Account
#

auth/account_schema.ts view source

Account

Account — authentication identity. You log in as an account.

id

type Uuid

username

email

type Email | null

email_verified

type boolean

password_hash

type string

created_at

type string

created_by

type Uuid | null

updated_at

type string

updated_by

type Uuid | null

Actor
#

auth/account_schema.ts view source

Actor

Actor — the entity that acts. Owns cells, holds role_grants, appears in audit trails.

id

type Uuid

account_id

type Uuid

name

type string

created_at

type string

updated_at

type string | null

updated_by

type Uuid | null

ActorSummaryJson
#

auth/account_schema.ts view source

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; name: ZodString; }, $strict>

Zod schema for the actor summary returned in admin account listings.

AdminAccountEntryJson
#

auth/account_schema.ts view source

ZodObject<{ account: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; updated_at: ZodString; updated_by: ZodNullable<...>; }, $strict>; actor: ZodNullable<...>; role_grants: ZodArray<...>; pending_offers: ZodArr...

Zod schema for an admin account listing entry (account + actor + role_grants + pending offers).

AdminAccountJson
#

auth/account_schema.ts view source

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; updated_at: ZodString; updated_by: ZodNullable<...>; }, $strict>

Zod schema for admin-facing account data — extends SessionAccountJson with audit fields.

ApiToken
#

auth/account_schema.ts view source

ApiToken

API token for CLI/programmatic access.

id

type string

account_id

type Uuid

name

type string

token_hash

type string

expires_at

type string | null

last_used_at

type string | null

last_used_ip

type string | null

created_at

type string

AuthSession
#

auth/account_schema.ts view source

AuthSession

Server-side auth session, keyed by blake3 hash of session token.

id

type string

account_id

type Uuid

created_at

type string

expires_at

type string

last_seen_at

type string

AuthSessionJson
#

auth/account_schema.ts view source

ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; }, $strict>

Zod schema for AuthSession — id is the blake3 hash, safe for client.

ClientApiTokenJson
#

auth/account_schema.ts view source

ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; name: ZodString; expires_at: ZodNullable<ZodString>; last_used_at: ZodNullable<...>; last_used_ip: ZodNullable<...>; created_at: ZodString; }, $strict>

Zod schema for client-safe API token listing (excludes token_hash).

CreateAccountInput
#

CreateRoleGrantInput
#

auth/account_schema.ts view source

CreateRoleGrantInput

actor_id

type Uuid

role

type string

scope_kind

Machine-readable kind for the scope_id. Required iff scope_id is set; must be null/omitted when scope_id is null. The DB-level role_grant_scope_kind_paired CHECK rejects mismatched pairs.

type string | null

scope_id

Scope the grant applies to. null / omitted grants a global role_grant.

type Uuid | null

expires_at

type Date | null

granted_by

type Uuid | null

source_offer_id

Offer id that produced this role_grant. Set by query_accept_offer; leave unset for direct grants.

type Uuid | null

is_role_grant_active
#

auth/account_schema.ts view source

(p: { revoked_at?: string | null | undefined; expires_at: string | null; }, now?: Date): boolean

p

type { revoked_at?: string | null | undefined; expires_at: string | null; }

now

type Date
default new Date()

returns

boolean

PendingOfferSummaryJson
#

auth/account_schema.ts view source

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_kind: ZodNullable<ZodString>; scope_id: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; from_actor_id: $ZodBranded<...>; from_username: ZodString; created_at: ZodString; expires_at: ZodString; }, $strict>

Zod schema for a pending role_grant offer surfaced in admin account listings.

Deliberately narrower than RoleGrantOfferJson: omits message and decline_reason so cross-admin visibility of the listing does not expose grantor-authored text that the audit log also withholds. Full offer payloads remain available through the offer-specific RPC surface and the audit log when admins need them.

from_username is resolved server-side so multi-admin deployments can see at a glance whose pending offer is blocking a "+ {role}" button; the resolution runs inside the listing query's parallel batch.

ROLE_GRANT_REVOKED_REASON_LENGTH_MAX
#

auth/account_schema.ts view source

500

Maximum length of the optional free-form revoked_reason attached to a revoked role_grant. Bounds the value at the schema layer so both the admin input (when the route surfaces a reason field) and the revokee-facing role_grant_revoke WS notification validate against the same ceiling.

RoleGrant
#

auth/account_schema.ts view source

RoleGrant

Role grant — time-bounded, revocable grant of a role to an actor.

id

type Uuid

actor_id

type Uuid

role

type string

scope_kind

Machine-readable kind tag for the polymorphic scope_id. Paired-null with scope_id per the role_grant_scope_kind_paired CHECK: both null (global) or both non-null (scoped). Consumer-declared via create_scope_kind_schema(...); v1 keeps validation registry-membership only, with no INSERT-time (role, scope_kind) enforcement.

type string | null

scope_id

Resource scope this grant applies to (e.g. a classroom id). null for global role_grants.

type Uuid | null

created_at

type string

expires_at

type string | null

revoked_at

type string | null

revoked_by

type Uuid | null

revoked_reason

Optional free-form reason attached on revoke (surfaced in the revokee WS notification once it lands).

type string | null

granted_by

type Uuid | null

source_offer_id

Offer that produced this role_grant (set by query_accept_offer). null for direct grants.

type Uuid | null

RoleGrantSummaryJson
#

auth/account_schema.ts view source

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_kind: ZodNullable<ZodString>; scope_id: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; created_at: ZodString; expires_at: ZodNullable<...>; granted_by: ZodNullable<...>; }, $strict>

Zod schema for the role_grant summary returned in admin account listings.

SessionAccount
#

auth/account_schema.ts view source

SessionAccount

Account without sensitive fields, scoped to the authenticated user's own session.

id

type Uuid

username

email

type Email | null

email_verified

type boolean

created_at

type string

SessionAccountJson
#

auth/account_schema.ts view source

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; }, $strict>

Zod schema for SessionAccount — account without sensitive fields.

to_admin_account
#

auth/account_schema.ts view source

(account: Account): { id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<...>) | null; }

Convert an Account to an AdminAccountJson for admin listings.

account

the full account record

type Account

returns

{ id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<"Uuid">) | null; }

the admin-safe account with audit fields

to_session_account
#

Depends on
#

Imported by
#