Skip to content
Oyster0.6.0
API reference

auth

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/oyster/auth";

Exports

Section titled “Exports”
Kind Export Description
type alias OysterKeySessionResolver The host owns session minting, hashing/storage and expiry. A session resolves only to a key id, never to owner or grant authority. Hosts should use Path=/, HttpOnly, Secure and SameSite=Lax (or stricter) as defense in depth; Oyster independently checks request provenance. Cookie-only admission allows GET/HEAD navigation. Every other method requires Origin to be present and equal the request URL’s origin, and Sec-Fetch-Site not to be cross-site. Missing Origin is refused.
constant ownerKeyCookieName Cookie emitted by ownerKeyAuth, for composing credential-specific adapters.
constant keySessionCookieName Host-minted opaque sessions for named keys, separate from the owner cookie.
function ownerKeyAuth() Single-owner sign-in: a bearer token or a session cookie holding the owner key’s digest. The key itself is never stored in the browser.
function ownerOrKeyAuth() The owner key, or a named key admitted as its canonical Team-key actor.
function keySessionAuth() Add host-owned browser sessions to ownerOrKeyAuth. Explicit credentials and non-401 refusals keep their ordinary result; ambient cookies cannot undo them. Every cookie admission rechecks the key’s liveness and canonical owner.

OysterKeySessionResolvertype alias

Section titled “OysterKeySessionResolver”
Signature
type OysterKeySessionResolver = Readonly<{
  resolve: (value) => Promise<Readonly<{
    keyId: string;
  }> | null>;
}>;

The host owns session minting, hashing/storage and expiry. A session resolves only to a key id, never to owner or grant authority. Hosts should use Path=/, HttpOnly, Secure and SameSite=Lax (or stricter) as defense in depth; Oyster independently checks request provenance. Cookie-only admission allows GET/HEAD navigation. Every other method requires Origin to be present and equal the request URL’s origin, and Sec-Fetch-Site not to be cross-site. Missing Origin is refused.

ownerKeyCookieNameconstant

Section titled “ownerKeyCookieName”
Signature
const ownerKeyCookieName: "oyster_session" = "oyster_session";

Cookie emitted by ownerKeyAuth, for composing credential-specific adapters.

keySessionCookieNameconstant

Section titled “keySessionCookieName”
Signature
const keySessionCookieName: "oyster_key_session" = "oyster_key_session";

Host-minted opaque sessions for named keys, separate from the owner cookie.

ownerKeyAuth()function

Section titled “ownerKeyAuth()”
Signature
function ownerKeyAuth(ownerKey, ownerId?): OysterAuth;

Single-owner sign-in: a bearer token or a session cookie holding the owner key’s digest. The key itself is never stored in the browser.

Parameters

Section titled “Parameters”
Parameter Type Default value
ownerKey string undefined
ownerId string "owner"

Returns

Section titled “Returns”

OysterAuth

ownerOrKeyAuth()function

Section titled “ownerOrKeyAuth()”
Signature
function ownerOrKeyAuth(ownerKey, ownerId, keys): OysterAuth;

The owner key, or a named key admitted as its canonical Team-key actor.

Parameters

Section titled “Parameters”
Parameter Type
ownerKey string
ownerId string
keys () => Pick<OysterKeyStore, "verify">

Returns

Section titled “Returns”

OysterAuth

keySessionAuth()function

Section titled “keySessionAuth()”
Signature
function keySessionAuth(auth, ownerId, keys, sessions): OysterAuth;

Add host-owned browser sessions to ownerOrKeyAuth. Explicit credentials and non-401 refusals keep their ordinary result; ambient cookies cannot undo them. Every cookie admission rechecks the key’s liveness and canonical owner.

Parameters

Section titled “Parameters”
Parameter Type
auth OysterAuth
ownerId string
keys () => NonNullable<OysterHost["keys"]>
sessions OysterKeySessionResolver

Returns

Section titled “Returns”

OysterAuth