lecodes-sdk 2.0.3 → 2.0.5

package/dist/types/server/auth/api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `db.auth` — the BUNDLE side of sign-in, what `*.server.ts` code calls on a db made with
+ * `defineDb({...}).withAuth({ model: "User" })`:
+ *
+ *   const db = defineDb({ User, Post }).withAuth({ model: "User" })
+ *
+ *   export async function register(login: string, password: string, name: string) {
+ *     await db.auth.signUpWithPassword(login, password, { name })
+ *   }
+ *   export async function me()                { return db.auth.user().select({ id: true, name: true }) }
+ *   export async function removePost(id: number) {
+ *     await db.auth.requireUser({ role: "admin" }).select({ id: true })
+ *     …
+ *   }
+ *
+ * The platform knows a request's session and the ID of its user (the host resolved the token before
+ * the endpoint ran). Everything else about a user is a row of the project's own model, and is READ:
+ * `user()` / `requireUser()` are queries over that model — typed by it, run when awaited — narrowed to
+ * the user of the request. Sign-in operations forward to the host's `AuthOps` on
+ * `globalThis.__lecodesAuth` (a seam: the compiled bundle carries its own SDK copy).
+ */
+/** The collections of a db with auth, by role (defineDb.ts). */
+export type AuthCollections = {
+    model: string;
+    user: any;
+    session: any;
+    identity: any;
+};
+export declare const createAuthApi: (tables: () => AuthCollections) => {
+    user: () => any;
+    requireUser: (where?: Record<string, unknown>) => any;
+    readonly sessionId: number;
+    signUpWithPassword: (login: string, password: string, data?: Record<string, unknown>) => Promise<void>;
+    signInWithPassword: (login: string, password: string) => Promise<void>;
+    setPassword: (password: string) => Promise<void>;
+    sendCode: (email: string) => Promise<void>;
+    signInWithCode: (email: string, code: string) => Promise<void>;
+    signIn: (userId: number) => Promise<void>;
+    signOut: () => Promise<void>;
+    readonly sessions: any;
+    readonly identities: any;
+};

package/dist/types/server/auth/appConfig.d.ts

@@ -1,16 +1,12 @@
 /**
- * The project's `app.json` subset the server runtime reads (name, auth providers).
+ * The project's `app.json` subset the server runtime reads: the app's name (the sign-in mail).
  *
  * This module is a placeholder the COMPILER REPLACES: `compileServerBundle({ app })` puts a module with the
  * real values at this same path in chisel's file map (project files win over SDK files), so every SDK module
  * that imports `app` gets the project's config as a plain dependency — no globals, no evaluation-order games.
  * Outside a compiled bundle (tests, tooling) `globalThis.__lecodesApp` can stand in.
  */
-export type AuthProvider = "email" | "google" | "apple" | "yandex" | "vk";
 export type AppConfig = {
     name?: string;
-    auth?: {
-        providers?: AuthProvider[];
-    };
 };
 export declare const app: AppConfig;

package/dist/types/server/auth/models.d.ts

@@ -1,31 +1,55 @@
 /**
- * `auth.model.user({...})` / `auth.model.session()` — the ONLY place auth touches the schema
- * (docs/backend-plan.md §3.4 / decision 10). Both return ordinary `model(...)`s: the developer registers
- * them in `defineDb({ User, Session, … })` under exactly those keys (other models relate to them with
- * `t.one("User")` / `t.one("Session")`), and `defineDb` adds `Session` itself when it isn't declared —
- * a device session exists from the first request, before any login, so every project db has one.
+ * The two models sign-in adds to a database — `defineDb({...}).withAuth({ model: "User" })`:
  *
- * Provider identity columns (`googleId`, `appleId`) follow `app.json` `auth.providers`, which the
- * compiler hands the server bundle through ./appConfig.ts (a module it replaces at compile time).
+ *   Session   one device: the hash of its token, and the user it is signed in as (none = a guest)
+ *   Identity  one way a user signs in: `email:<address>` or `login:<name>` (with the password's hash
+ *             when one is set) — several per user.
+ *
+ * They are the PLATFORM's: a project never declares them and never writes to them — it may refer to a
+ * session (`t.one("Session")`: a guest's cart) and read both through `db.auth.sessions` /
+ * `db.auth.identities`, which leave the secrets out. The user model is the project's own, an ordinary
+ * `model({...})`: the platform creates a row of it the first time someone signs in and knows nothing
+ * of it but the id.
  */
-import { type Field } from "../db/fields";
-import type { Fields, Model } from "../db/types";
-import { type AppConfig, type AuthProvider } from "./appConfig";
-export type { AppConfig, AuthProvider };
-/** The project's `app.json` subset: the compiled-in module, else the test/tooling seam, else empty. */
-export declare const appConfig: () => AppConfig;
-export declare const enabledProviders: () => AuthProvider[];
-/** The model name the auth runtime binds to. */
-export declare const AUTH_USER_MODEL = "User";
+export type { AppConfig } from "./appConfig";
+/** What an `Identity` row is of: an email, or a login (a name with no address behind it). */
+export type IdentityProvider = "email" | "login";
 export declare const AUTH_SESSION_MODEL = "Session";
-/** Marker on the two auth models (`model()` objects are otherwise plain). */
-export type AuthModelKind = "user" | "session";
-export type AuthModel<F extends Fields> = Model<F> & {
-    readonly __auth: AuthModelKind;
+export declare const AUTH_IDENTITY_MODEL = "Identity";
+/** A session as a project reads it (`db.auth.sessions`, a `t.one("Session")` relation). */
+export declare const sessionPublicFields: () => {
+    createdAt: import("../db").Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    lastSeenAt: import("../db").Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    revoked: import("../db").Field<boolean, {
+        kind: "scalar";
+        scalar: "bool";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
 };
-/** Built-in `User` fields (what `auth.user` is typed with). */
-export declare const userFields: () => {
-    email: Field<string, {
+export type SessionPublicFields = ReturnType<typeof sessionPublicFields>;
+/** The whole `Session`; `user` points at the model `withAuth` named. */
+export declare const sessionFields: (userModel: string) => {
+    pendingEmail: import("../db").Field<string, {
         kind: "scalar";
         scalar: "string";
         optional: true;
@@ -34,7 +58,7 @@ export declare const userFields: () => {
         isId: false;
         model: "";
     }>;
-    name: Field<string, {
+    codeHash: import("../db").Field<string, {
         kind: "scalar";
         scalar: "string";
         optional: true;
@@ -43,45 +67,34 @@ export declare const userFields: () => {
         isId: false;
         model: "";
     }>;
-    avatar: Field<string, {
+    codeExpires: import("../db").Field<number, {
         kind: "scalar";
-        scalar: "string";
+        scalar: "date";
         optional: true;
         hasDefault: false;
         array: false;
         isId: false;
         model: "";
     }>;
-    /** Plain string column, `"user"` by default — `auth.requireUser({ role: "admin" })` is field equality. */
-    role: Field<string, {
+    codeAttempts: import("../db").Field<number, {
         kind: "scalar";
-        scalar: "string";
+        scalar: "int";
         optional: false;
         hasDefault: true;
         array: false;
         isId: false;
         model: "";
     }>;
-    createdAt: Field<number, {
-        kind: "scalar";
-        scalar: "date";
-        optional: false;
-        hasDefault: true;
+    user: import("../db").Field<never, {
+        kind: "one";
+        scalar: "";
+        optional: true;
+        hasDefault: false;
         array: false;
         isId: false;
-        model: "";
+        model: string;
     }>;
-};
-export type UserFields = ReturnType<typeof userFields>;
-/** Built-in `Session` fields. `user` is added by `defineDb` when a `User` model exists (schema-time, so a
- *  db without an auth user model has sessions without a user column). */
-export declare const sessionFields: () => {
-    /** sha256 of the bearer token the device holds — the token itself is never stored. */
-    tokenHash: Field<string, import("../db/fields").Meta<{
-        kind: "scalar";
-        scalar: "string";
-    }>>;
-    createdAt: Field<number, {
+    createdAt: import("../db").Field<number, {
         kind: "scalar";
         scalar: "date";
         optional: false;
@@ -90,7 +103,7 @@ export declare const sessionFields: () => {
         isId: false;
         model: "";
     }>;
-    lastSeenAt: Field<number, {
+    lastSeenAt: import("../db").Field<number, {
         kind: "scalar";
         scalar: "date";
         optional: false;
@@ -99,7 +112,7 @@ export declare const sessionFields: () => {
         isId: false;
         model: "";
     }>;
-    revoked: Field<boolean, {
+    revoked: import("../db").Field<boolean, {
         kind: "scalar";
         scalar: "bool";
         optional: false;
@@ -108,16 +121,54 @@ export declare const sessionFields: () => {
         isId: false;
         model: "";
     }>;
-    pendingEmail: Field<string, {
+    /** sha256 of the bearer token the device holds — the token itself is never stored. */
+    tokenHash: import("../db").Field<string, import("../db/fields").Meta<{
         kind: "scalar";
         scalar: "string";
+    }>>;
+};
+/** A sign-in method as a project reads it (`db.auth.identities`) — no hash. */
+export declare const identityPublicFields: () => {
+    /** `"email" | "login"` */
+    provider: import("../db").Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** What the person types to sign in: the address, or the login. */
+    subject: import("../db").Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** When the subject was proven (a code). Unset = a password sign-up whose address wasn't confirmed. */
+    verifiedAt: import("../db").Field<number, {
+        kind: "scalar";
+        scalar: "date";
         optional: true;
         hasDefault: false;
         array: false;
         isId: false;
         model: "";
     }>;
-    codeHash: Field<string, {
+    createdAt: import("../db").Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+};
+export type IdentityPublicFields = ReturnType<typeof identityPublicFields>;
+/** The whole `Identity`. */
+export declare const identityFields: (userModel: string) => {
+    /** `<provider>:<subject>` — marcidb has no composite @unique, this is the one-row-per-identity guarantee. */
+    key: import("../db").Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** scrypt hash of the password (`email` / `login` identities). */
+    hash: import("../db").Field<string, {
         kind: "scalar";
         scalar: "string";
         optional: true;
@@ -126,7 +177,18 @@ export declare const sessionFields: () => {
         isId: false;
         model: "";
     }>;
-    codeExpires: Field<number, {
+    /** `"email" | "login"` */
+    provider: import("../db").Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** What the person types to sign in: the address, or the login. */
+    subject: import("../db").Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    /** When the subject was proven (a code). Unset = a password sign-up whose address wasn't confirmed. */
+    verifiedAt: import("../db").Field<number, {
         kind: "scalar";
         scalar: "date";
         optional: true;
@@ -135,30 +197,17 @@ export declare const sessionFields: () => {
         isId: false;
         model: "";
     }>;
-    codeAttempts: Field<number, {
+    createdAt: import("../db").Field<number, {
         kind: "scalar";
-        scalar: "int";
+        scalar: "date";
         optional: false;
         hasDefault: true;
         array: false;
         isId: false;
         model: "";
     }>;
+    user: import("../db").Field<never, import("../db/fields").Meta<{
+        kind: "one";
+        model: string;
+    }>>;
 };
-export type SessionFields = ReturnType<typeof sessionFields> & {
-    user: ReturnType<typeof sessionUserField>;
-};
-export declare const sessionUserField: () => Field<never, {
-    kind: "one";
-    scalar: "";
-    optional: true;
-    hasDefault: false;
-    array: false;
-    isId: false;
-    model: "User";
-}>;
-/** `auth.model.user({...extra})` — the built-in user (+ provider ids from app.json) plus the developer's fields. */
-export declare const authUserModel: <E extends Fields = {}>(extra?: E) => AuthModel<UserFields & E>;
-/** `auth.model.session({...extra})` — declare it only to relate to sessions (`t.one("Session")`) or to add fields. */
-export declare const authSessionModel: <E extends Fields = {}>(extra?: E) => AuthModel<SessionFields & E>;
-export declare const isAuthModel: (m: unknown, kind?: AuthModelKind) => m is AuthModel<any>;

package/dist/types/server/auth/types.d.ts

@@ -1,56 +1,32 @@
 /**
- * Shared shapes of the auth layer (docs/backend-plan.md §3.4). Two sides meet through them:
- *  - the BUNDLE side (`auth` global, ./global.ts) — what `*.server.ts` code calls;
- *  - the HOST side (./host.ts) — sessions, email codes and OAuth binding, run by the runner with the
- *    project's db handle and the platform's secrets. Installed on `globalThis.__lecodesAuth`.
+ * Shared shapes of the auth layer. Two sides meet through them:
+ *  - the BUNDLE side (`db.auth`, ./api.ts) — what `*.server.ts` code calls;
+ *  - the HOST side (./host.ts) — sessions, passwords and email codes, run by the runner with the
+ *    project's db handle. Installed on `globalThis.__lecodesAuth`.
  */
 import type { RequestContext } from "../context";
-import type { AuthProvider } from "./models";
-/** The built-in user row — what `auth.user` is typed with (custom fields exist at runtime; select them via `db.user`). */
-export type AuthUser = {
-    id: number;
-    email: string | null;
-    name: string | null;
-    avatar: string | null;
-    role: string;
-    createdAt: number;
-};
-/** Per-request auth state, resolved by the host before the endpoint runs (`RequestContext.auth`). */
+/** Per-request auth state, resolved by the host before the endpoint runs (`RequestContext.auth`): the
+ *  device's session and the id of the user it is signed in as. Nothing of the user's row — a project
+ *  reads that itself (`db.auth.user()`). */
 export type AuthState = {
     sessionId: number;
     userId: number | null;
-    user: AuthUser | null;
     /** A token to hand back to the client in this response (a new guest session, or a rotation). */
     issuedToken?: string;
 };
-/** What an OAuth provider hands the runner after a successful web sign-in. */
-export type OAuthProfile = {
-    sub: string;
-    email?: string | null;
-    emailVerified?: boolean;
-    name?: string | null;
-    avatar?: string | null;
-};
-/** A credential a NATIVE provider SDK produced in the app (client plugin `OAuth.signIn`): an access token
- *  (Yandex, VK ID) or an OpenID identity token (Google, Apple). Verified server-side, never trusted as-is. */
-export type OAuthCredential = {
-    accessToken?: string;
-    idToken?: string;
-    name?: string | null;
-    email?: string | null;
-};
-/** Host operations the bundle's `auth` global forwards to (all request-scoped through `ctx`). */
+/** Host operations `db.auth` forwards to (all request-scoped through `ctx`). A sign-in resolves once the
+ *  session is bound; who it is bound to is read through `db.auth.user()`. */
 export type AuthOps = {
-    email: {
-        sendCode(ctx: RequestContext, email: string): Promise<void>;
-        verify(ctx: RequestContext, email: string, code: string): Promise<AuthUser>;
-    };
-    oauth: {
-        url(ctx: RequestContext, provider: Exclude<AuthProvider, "email">): Promise<string>;
-        signIn(ctx: RequestContext, provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser>;
-    };
-    signIn(ctx: RequestContext, userId: number): Promise<AuthUser>;
+    /** `data` = the fields of the new user's row (the project's own model). */
+    signUpWithPassword(ctx: RequestContext, login: string, password: string, data?: Record<string, unknown>): Promise<void>;
+    signInWithPassword(ctx: RequestContext, login: string, password: string): Promise<void>;
+    setPassword(ctx: RequestContext, password: string): Promise<void>;
+    sendCode(ctx: RequestContext, email: string): Promise<void>;
+    signInWithCode(ctx: RequestContext, email: string, code: string): Promise<void>;
+    signIn(ctx: RequestContext, userId: number): Promise<void>;
     signOut(ctx: RequestContext): Promise<void>;
-    /** `db.session` filtered to the current user's sessions (or just this device's, when signed out). */
+    /** The sessions of the current user (or just this device's, when signed out), as a query. */
     sessions(ctx: RequestContext): any;
+    /** The current user's sign-in methods, as a query — the hash is not in it. */
+    identities(ctx: RequestContext): any;
 };

package/dist/types/server/channel.d.ts

@@ -1,28 +1,66 @@
 /**
- * Server side of channels (docs/backend-plan.md §3.3): typed pub/sub, server → client only.
+ * Channels: the server's messages to the app. A server function is a call from the app to the
+ * server; a channel is the other direction, typed by the same export.
  *
- *   type ChatEvents = { message: { from: string; text: string }; typing: { from: string } }
- *   export const chat = channel<ChatEvents>({ onJoin: room => { auth.requireUser() } })
- *   chat.publish(room, "message", { from, text })
+ *   export const postsChannel = channel<Post>()                       // to everyone listening
+ *   export const noticesChannel = channel<Notice>()                   // to each their own
+ *     .groupBy(async () => (await db.auth.requireUser().select({ id: true })).id)
+ *
+ *   postsChannel.publish(post)                  // server
+ *   noticesChannel.publish(userId, notice)
+ *
+ *   postsChannel.subscribe(post => …)           // app
+ *   noticesChannel.subscribe(notice => …)
+ *
+ * `groupBy` runs on the server when an app subscribes, with what the app passed to `subscribe`
+ * before the handler, and answers the group that subscriber is in; `publish(group, message)` reaches
+ * that group. `authorize` only decides who may listen. Both refuse by throwing (`ApiError`), and
+ * both run in the request scope of the subscriber, so `db.auth` works in them.
  *
  * A channel's identity is its export (`<path>#<name>`), assigned by the runtime when the bundle is
  * loaded (`loadServerModules`); `publish` before that is an error. Delivery goes through the
- * `globalThis.__lecodesPublish` seam the runner installs (same reason as ./context.ts: the bundle
- * carries its own SDK copy).
+ * `globalThis.__lecodesPublish` seam the host installs (same reason as ./context.ts: the bundle
+ * carries its own SDK copy). In the app the export is another object altogether — the proxy
+ * `__channel` of src/runtime/rpc.ts — which is why `subscribe` here only throws.
  */
-export type ChannelEvents = Record<string, unknown>;
-export type ChannelOptions = {
-    /** Called when a client subscribes to `topic`; throw (e.g. `ApiError(403)`) to refuse. */
-    onJoin?: (topic: string) => void | Promise<void>;
+import type { ChannelGroup } from "../runtime/wire";
+export type { ChannelGroup };
+/** What `subscribe` answers: the subscription lives until `close()`. */
+export type ChannelSubscription = {
+    close(): void;
 };
-export interface Channel<E extends ChannelEvents> {
-    readonly options: ChannelOptions;
-    /** Deliver `event` with `payload` to every subscriber of `topic` (at-most-once). */
-    publish<K extends keyof E & string>(topic: string, event: K, payload: E[K]): void;
+export type SubscribeOptions = {
+    /** The connection dropped and came back: what was published in between is lost — read the state again. */
+    reconnect?: () => void;
+    /** The server refused the subscription (a hook threw): an `RpcError`, its `status` the hook's.
+     *  Without it the refusal is logged. The subscription is not over: the server is asked again
+     *  when the session changes, so this may be called more than once. */
+    error?: (e: Error & {
+        readonly status: number;
+    }) => void;
+};
+/** A channel every subscriber hears alike. */
+export interface Channel<M> {
+    /** Who may listen: runs on the server at every subscription, throw to refuse. */
+    authorize(check: () => void | Promise<void>): Channel<M>;
+    /** Split the subscribers: `group` runs on the server at every subscription — with what the app
+     *  passed to `subscribe` — and answers the group of that subscriber. Throw to refuse. */
+    groupBy<K extends ChannelGroup, A extends unknown[] = []>(group: (...args: A) => K | Promise<K>): GroupedChannel<M, K, A>;
+    /** Server: send `message` to every subscriber (at most once — nothing is kept for a socket that is away). */
+    publish(message: M): void;
+    /** App: listen until `close()`. */
+    subscribe(handler: (message: M) => void, options?: SubscribeOptions): ChannelSubscription;
+}
+/** A channel whose subscribers are in groups (`groupBy`). */
+export interface GroupedChannel<M, K extends ChannelGroup, A extends unknown[]> {
+    /** Server: send `message` to the subscribers of `group`. */
+    publish(group: K, message: M): void;
+    /** App: listen until `close()`; the arguments before the handler go to the channel's `groupBy`. */
+    subscribe(...args: [...args: A, handler: (message: M) => void, options?: SubscribeOptions]): ChannelSubscription;
 }
-type Publisher = (channelId: string, topic: string, event: string, payload: unknown) => void;
-/** Host hook (runner / test harness): where `publish` delivers to. */
+type Publisher = (channelId: string, group: ChannelGroup | null, message: unknown) => void;
+/** Host hook (runner / local backend / test harness): where `publish` delivers to. */
 export declare const setChannelPublisher: (publisher: Publisher | null) => void;
-export declare const channel: <E extends ChannelEvents>(options?: ChannelOptions) => Channel<E>;
-export declare const isChannel: (v: unknown) => v is Channel<any>;
-export {};
+export declare const isChannelGroup: (v: unknown) => v is ChannelGroup;
+export declare const channel: <M = unknown>() => Channel<M>;
+export declare const isChannel: (v: unknown) => v is ChannelRecord;

package/dist/types/server/context.d.ts

@@ -6,13 +6,13 @@
  * timers after the response) every member is undefined.
  */
 export type RequestContext = {
-    /** Endpoint id `<path>#<export>` (or the channel id for `onJoin`). */
+    /** Endpoint id `<path>#<export>` (or the channel id for a subscription's hooks). */
     id: string;
     headers: Record<string, string>;
     ip?: string;
     /** Bearer session token as sent by the client transport (raw; auth resolves it). */
     sessionToken?: string;
-    /** Set by the auth runtime after resolving the token — read via `auth.*`, not here. */
+    /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
     auth?: unknown;
 };
 type Provider = () => RequestContext | undefined;

package/dist/types/server/db/defineDb.d.ts

@@ -32,5 +32,15 @@ export declare const toMarci: (metas: Record<string, ModelMeta>) => string;
 export type DefineDbOptions = {
     transport?: MarciTransport;
 };
+/**
+ * The schema registry: model name = key (`db.user` ← `User`). Relation strings are checked against the
+ * keys both at the type level (`ValidateRefs`) and at runtime.
+ *
+ * A db is SEALED by its first use — a query, a read of its schema, the host taking it after the file
+ * has loaded. Until then `.withAuth({ model })` may still change what it holds: it adds the platform's
+ * `Session` and `Identity` models (../auth/models.ts) pointing at the project's model of a user, and
+ * gives the db its `auth`. So `withAuth` belongs to the definition, written on `defineDb(...)` itself;
+ * on a db that has been used it throws.
+ */
 export declare const defineDb: <const S extends Schema>(declared: S & ValidateRefs<S>, options?: DefineDbOptions) => Db<S>;
 export {};

package/dist/types/server/db/index.d.ts

@@ -2,5 +2,5 @@ export { t } from "./fields";
 export type { Field, FieldDef, FieldMeta } from "./fields";
 export { model, defineDb, ref, setDbTransport, toMarci } from "./defineDb";
 export type { DefineDbOptions } from "./defineDb";
-export type { Db, Model, Schema, Row, Id, Insert, Update, Select, Where, Query, QueryObject, Result, Collection, ScalarSelect, Types } from "./types";
+export type { Auth, Db, DbWithAuth, UserQuery, Model, Schema, Row, Id, Insert, Update, Select, Where, Query, QueryObject, Result, Collection, ScalarSelect, Types } from "./types";
 export type { Op, MarciOp, MarciTransport, JsonValue, Sub } from "./marci/query";