Skip to content
Oyster0.6.0
API reference

tenancy

Exports

Section titled “Exports”
Kind Export Description
type alias Identity An external identity; the registry owns its canonical member mapping.
type alias Tenant One provisioned tenant and its registry-owned canonical public origin.
type alias Membership A live membership, carrying a stored host-owned member identity.
type alias ReadonlyTenantRegistry Reads existing authority; this port cannot mutate tenants or members.
type alias TenantCreateInput A single create transition records tenant and owner membership together.
type alias ManagedTenantRegistry Mutable registry owner; remove is called only after teardown succeeds.
type alias TenantResolverAdapter Request URL resolution, with an explicit origin/path distinction.
type alias AuthResult Adapter output: pass only when the presented credential is not this adapter’s.
type alias AuthAdapter Authentication proves an identity, or attests a principal for this tenant.
type alias TenancyPolicy Abuse-only admission policy; it does not meter or bill usage.
type alias TenancyHooks Lifecycle callbacks run after create and before physical deletion.
type alias TenancyAdmission Typed result of tenant authentication and abuse-policy admission.
type alias TenancyVariables Typed Hono context fields populated only after admission.
type alias ReadonlyTenancy Read-only host API; no create/delete methods are exposed.
type alias ManagedTenancy Managed hosts can provision tenants and run teardown through the kit.
type alias TenancyConfig Configuration composes resolution, live registry authority and auth adapters.
function createTenancy()

Identitytype alias

Section titled “Identity”
Signature
type Identity = Readonly<{
  provider: string;
  subject: string;
  email?: string;
}>;

An external identity; the registry owns its canonical member mapping.

Tenanttype alias

Section titled “Tenant”
Signature
type Tenant = Readonly<{
  id: TenantId;
  handle: string;
  origin: string;
  status: "active" | "suspended" | "deleting";
  owners: readonly string[];
  domains: readonly string[];
}>;

One provisioned tenant and its registry-owned canonical public origin.

Membershiptype alias

Section titled “Membership”
Signature
type Membership = Readonly<{
  memberId: string;
  role: "owner" | "member";
  membershipVersion: number;
}>;

A live membership, carrying a stored host-owned member identity.

ReadonlyTenantRegistrytype alias

Section titled “ReadonlyTenantRegistry”
Signature
type ReadonlyTenantRegistry = Readonly<{
  get: Promise<Readonly<{
    id: TenantId;
    handle: string;
    origin: string;
    status: "active" | "suspended" | "deleting";
    owners: readonly string[];
    domains: readonly string[];
  }> | null>;
  byHandle: Promise<Readonly<{
    id: TenantId;
    handle: string;
    origin: string;
    status: "active" | "suspended" | "deleting";
    owners: readonly string[];
    domains: readonly string[];
  }> | null>;
  byDomain?: Promise<Readonly<{
    id: TenantId;
    handle: string;
    origin: string;
    status: "active" | "suspended" | "deleting";
    owners: readonly string[];
    domains: readonly string[];
  }> | null>;
  status: Promise<"active" | "suspended" | "deleting" | null>;
  membershipOf: Promise<Readonly<{
    memberId: string;
    role: "owner" | "member";
    membershipVersion: number;
  }> | null>;
  memberById: Promise<Readonly<{
    memberId: string;
    role: "owner" | "member";
    membershipVersion: number;
  }> | null>;
}>;

Reads existing authority; this port cannot mutate tenants or members.

TenantCreateInputtype alias

Section titled “TenantCreateInput”
Signature
type TenantCreateInput = Readonly<{
  handle: string;
  origin: string;
  domains: readonly string[];
  owner: Identity;
}>;

A single create transition records tenant and owner membership together.

ManagedTenantRegistrytype alias

Section titled “ManagedTenantRegistry”
Signature
type ManagedTenantRegistry = ReadonlyTenantRegistry &
  Readonly<{
    create: Promise<
      Readonly<{
        id: TenantId;
        handle: string;
        origin: string;
        status: "active" | "suspended" | "deleting";
        owners: readonly string[];
        domains: readonly string[];
      }>
    >;
    setStatus: Promise<void>;
    delete: Promise<void>;
  }>;

Mutable registry owner; remove is called only after teardown succeeds.

TenantResolverAdaptertype alias

Section titled “TenantResolverAdapter”
Signature
type TenantResolverAdapter<Kind> = Readonly<{
  kind: Kind;
  resolve: Promise<(string & Brand<"OysterTenantId">) | null>;
}>;

Request URL resolution, with an explicit origin/path distinction.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Kind extends "origin" | "path" "origin" | "path"

AuthResulttype alias

Section titled “AuthResult”
Signature
type AuthResult =
  | Readonly<{
      kind: "identity";
      identity: Identity;
    }>
  | Readonly<{
      kind: "principal";
      principal: TenantPrincipal;
    }>
  | Readonly<{
      kind: "pass";
    }>
  | Readonly<{
      kind: "refused";
      status: 401 | 403;
    }>;

Adapter output: pass only when the presented credential is not this adapter’s.

AuthAdaptertype alias

Section titled “AuthAdapter”
Signature
type AuthAdapter = Readonly<{
  id: string;
  routes?: Hono;
  authenticate: Promise<AuthResult>;
}>;

Authentication proves an identity, or attests a principal for this tenant.

TenancyPolicytype alias

Section titled “TenancyPolicy”
Signature
type TenancyPolicy = (context) => Promise<
  | Readonly<{
      kind: "allow";
    }>
  | Readonly<{
      kind: "refuse";
      status: 429;
      retryAfter: number;
    }>
>;

Abuse-only admission policy; it does not meter or bill usage.

Parameters

Section titled “Parameters”
Parameter Type
context Readonly<{ tenant: Tenant; principal: TenantPrincipal; request: Request; }>

Returns

Section titled “Returns”

Promise< | Readonly<{ kind: "allow"; }> | Readonly<{ kind: "refuse"; status: 429; retryAfter: number; }>>

TenancyHookstype alias

Section titled “TenancyHooks”
Signature
type TenancyHooks = Readonly<{
  tenant.created?: (context) => Promise<void>;
  tenant.deleting?: (context) => Promise<void>;
}>;

Lifecycle callbacks run after create and before physical deletion.

TenancyAdmissiontype alias

Section titled “TenancyAdmission”
Signature
type TenancyAdmission =
  | Readonly<{
      kind: "admitted";
      tenant: Tenant;
      principal: TenantPrincipal;
    }>
  | Readonly<{
      kind: "refused";
      status: 401 | 403 | 404 | 429;
      retryAfter?: number;
    }>;

Typed result of tenant authentication and abuse-policy admission.

TenancyVariablestype alias

Section titled “TenancyVariables”
Signature
type TenancyVariables = object;

Typed Hono context fields populated only after admission.

Properties

Section titled “Properties”

tenant

Section titled “tenant”
Signature
tenant: Tenant;

The admitted provisioned tenant.

principal

Section titled “principal”
Signature
principal: TenantPrincipal;

The admitted canonical principal.

ReadonlyTenancytype alias

Section titled “ReadonlyTenancy”
Signature
type ReadonlyTenancy<Kind> = Readonly<{
  resolve: Promise<Readonly<{
    id: TenantId;
    handle: string;
    origin: string;
    status: "active" | "suspended" | "deleting";
    owners: readonly string[];
    domains: readonly string[];
  }> | null>;
  authenticate: Promise<TenancyAdmission>;
  member: Promise<TenantPrincipal | null>;
  memberById: Promise<
    (TenantPrincipal & Readonly<{ membershipVersion: number }>) | null
  >;
  middleware: MiddlewareHandler<{
    Variables: TenancyVariables;
  }>;
}> &
  Kind extends "origin"
  ? Readonly<{
      oyster: OysterTenancy;
    }>
  : Record<never, never>;

Read-only host API; no create/delete methods are exposed.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Kind extends "origin" | "path" "origin" | "path"

ManagedTenancytype alias

Section titled “ManagedTenancy”
Signature
type ManagedTenancy<Kind> = ReadonlyTenancy<Kind> &
  Readonly<{
    create: Promise<
      Readonly<{
        id: TenantId;
        handle: string;
        origin: string;
        status: "active" | "suspended" | "deleting";
        owners: readonly string[];
        domains: readonly string[];
      }>
    >;
    delete: Promise<void>;
  }>;

Managed hosts can provision tenants and run teardown through the kit.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Kind extends "origin" | "path" "origin" | "path"

TenancyConfigtype alias

Section titled “TenancyConfig”
Signature
type TenancyConfig<Registry, Kind> = Readonly<{
  resolve: TenantResolverAdapter<Kind>;
  registry: Registry;
  auth: readonly AuthAdapter[];
  policy?: TenancyPolicy;
  on?: TenancyHooks;
}>;

Configuration composes resolution, live registry authority and auth adapters.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Registry extends ReadonlyTenantRegistry ReadonlyTenantRegistry
Kind extends "origin" | "path" "origin" | "path"

createTenancy()function

Section titled “createTenancy()”

Call Signature

Section titled “Call Signature”
Signature
function createTenancy<Kind>(config): ManagedTenancy<Kind>;

Managed registries expose provisioning and cleanup; readonly registries do not.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "path" | "origin"

Parameters

Section titled “Parameters”
Parameter Type
config TenancyConfig<ManagedTenantRegistry, Kind>

Returns

Section titled “Returns”

ManagedTenancy<Kind>

Call Signature

Section titled “Call Signature”
Signature
function createTenancy<Kind>(config): ReadonlyTenancy<Kind>;

Resolve and authenticate requests without exposing registry mutations.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Kind extends "path" | "origin"

Parameters

Section titled “Parameters”
Parameter Type
config TenancyConfig<ReadonlyTenantRegistry, Kind>

Returns

Section titled “Returns”

ReadonlyTenancy<Kind>