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`

type 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
#

auth/account_schema.ts view source

CreateAccountInput

`username`

type Username

`password_hash`

type string

`email`

type Email | null

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`

type 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
#

auth/account_schema.ts view source

(account: Account): SessionAccount

Convert an Account to a SessionAccount by stripping sensitive fields.

`account`

the full account record

type Account

returns

SessionAccount

the client-safe account

Depends on
#

primitive_schemas.ts