Access

import * as mod from "jsr:@nzip/lofi/access";

Narrow private, direct-share, and fixed-role group access templates over raw Jazz schemas.

Use privateAccess, sharedAccess, or groupAccess to declare common authorization models. Runtime operations require managed sync for collaboration and throw AccessError when that precondition is not met. Raw Jazz policy callbacks remain available through defineAccessPolicies.

AccessError

^class

class AccessError extends Error {
  constructor(code: AccessErrorCode, message: string, options?: ErrorOptions);
  readonly name: string;
}

Actionable failure raised by access templates and collaboration operations.

createGroupOperations

^function

function createGroupOperations<Group extends Identified, GroupInit, Member extends GroupMembershipRow, MemberInit>(config: { groups: AccessRuntimeTable<Group, GroupInit>; members: AccessRuntimeTable<Member, MemberInit> }): GroupOperations<Group, GroupInit, Member>

Creates fixed-role group membership operations for a declared table pair.

createSharingOperations

^function

function createSharingOperations<Resource extends Identified, ResourceInit, Grant extends SharedGrantRow, GrantInit>(config: { resource: AccessRuntimeTable<Resource, ResourceInit>; grants: AccessRuntimeTable<Grant, GrantInit> }): SharingOperations<Resource, Grant>

Creates direct-share operations that wait for local and global durability.

decodeSharingIdentity

^function

function decodeSharingIdentity(identity: string): string

Validates an app-scoped sharing identity and returns its raw Jazz principal. Surrounding whitespace from copy/paste is tolerated; whitespace inside the principal is rejected — a grant for a padded principal would look active to the owner while never matching the recipient's actual account.

defineAccessPolicies

^function

function defineAccessPolicies<TApp extends object>(app: TApp, templates: readonly AccessTemplate[], raw?: RawAccessPolicyExtension): CompiledPermissions

Compiles the three narrow templates through Jazz's own policy builder. The optional callback is the raw Jazz-policy escape hatch for app-specific rules.

| Parameter | Description |

| --- | --- |

| app | The raw Jazz app returned by s.defineApp. |

| templates | At least one privateAccess, sharedAccess, or groupAccess template; every table needs a policy. |

| raw | Optional raw-policy callback for app-specific rules beyond the templates. |

Returns: Compiled permissions suitable as the app's default policy export.

Example

import { defineAccessPolicies, groupAccess, sharedAccess } from "@nzip/lofi/access";
import { app } from "./schema.ts";

export default defineAccessPolicies(app, [
  sharedAccess({ resource: app.notes, grants: app.noteGrants }),
  groupAccess({
    groups: app.workspaces,
    members: app.workspaceMembers,
    resources: app.documents,
    groupId: "workspaceId",
  }),
]);

encodeSharingIdentity

^function

function encodeSharingIdentity(userId: string): SharingIdentity

Encodes a raw Jazz principal as a versioned identity scoped to the current app.

groupAccess

^function

function groupAccess(config: { groups: AccessTable; members: AccessTable; resources: AccessTable | readonly AccessTable[]; groupId: string }): GroupAccessTemplate

Declares fixed-role membership policy for one or more group-owned resources.

The membership table must be declared with the groupMembershipTable helper (or match its column shape), and each resource table must carry the groupId column referencing the group table.

| Parameter | Description |

| --- | --- |

| config | The group table, membership table, group-owned resource table(s), and the resource column that references the group. |

Returns: A template for defineAccessPolicies.

Example

import { defineAccessPolicies, groupAccess } from "@nzip/lofi/access";
import { app } from "./schema.ts";

export default defineAccessPolicies(app, [groupAccess({
  groups: app.workspaces,
  members: app.workspaceMembers,
  resources: app.documents,
  groupId: "workspaceId",
})]);

groupMembershipTable

^function

function groupMembershipTable<Group extends string>(group: Group): DefinedTable<{ groupId: RefColumn<Group>; user_id: StringColumn; role: StringColumn; can_create: BooleanColumn; can_edit_any: BooleanColumn; can_manage: BooleanColumn }>

Creates the conventional relationship table used by groupAccess.

groupRoleCapabilities

^function

function groupRoleCapabilities(role: GroupRole): { readonly role: GroupRole; readonly can_create: boolean; readonly can_edit_any: boolean; readonly can_manage: boolean }

Returns the persisted capability flags for a fixed group role.

groupRoles

^const

const groupRoles: ("reader" | "contributor" | "writer" | "admin")[];

Fixed Wave 2 group roles. Custom role systems remain a raw Jazz escape hatch.

isAccessError

^function

function isAccessError(error: unknown): error is AccessError

True when an error came from the lofi access surface.

privateAccess

^function

function privateAccess(config: { resource: AccessTable }): PrivateAccessTemplate

Declares owner-only read and mutation policy for one resource table.

| Parameter | Description |

| --- | --- |

| config | The resource table whose rows are visible and mutable only to their creator. |

Returns: A template for defineAccessPolicies.

Example

import { defineAccessPolicies, privateAccess } from "@nzip/lofi/access";
import { app } from "./schema.ts";

export default defineAccessPolicies(app, [privateAccess({ resource: app.notes })]);

sharedAccess

^function

function sharedAccess(config: { resource: AccessTable; grants: AccessTable }): SharedAccessTemplate

Declares owner plus explicit read/edit grants for one resource table.

The grant table must be declared with the sharedGrantTable helper (or match its column shape) and reference the resource table.

| Parameter | Description |

| --- | --- |

| config | The shared resource table and its grant table. |

Returns: A template for defineAccessPolicies.

Example

import { defineAccessPolicies, sharedAccess } from "@nzip/lofi/access";
import { app } from "./schema.ts";

export default defineAccessPolicies(app, [
  sharedAccess({ resource: app.notes, grants: app.noteGrants }),
]);

sharedGrantTable

^function

function sharedGrantTable<Resource extends string>(resource: Resource): DefinedTable<{ resourceId: RefColumn<Resource>; user_id: StringColumn; can_edit: BooleanColumn }>

Creates the conventional relationship table used by sharedAccess.

sharingIdentity

^function

async function sharingIdentity(): Promise<SharingIdentity>

Returns the non-secret, app-scoped identity users may copy for shares.

AccessErrorCode

^type

type AccessErrorCode = 
  | "configuration"
  | "invalid-identity"
  | "sync-required"
  | "mutation-rejected"
  | "not-found"
  | "invalid-role";

Stable categories for access configuration and collaboration failures.

AccessRuntimeTable

^type

type AccessRuntimeTable<Row, Init> = TableProxy<Row, Init> & { where(input: unknown): QueryBuilder<Row> };

Jazz table shape required by the access operation helpers.

AccessTable

^type

type AccessTable = {
  readonly _table: string;
  readonly _schema: Record<string, { columns?: unknown[] }>;
};

Minimum declared Jazz table metadata consumed by access templates.

AccessTemplate

^type

type AccessTemplate = PrivateAccessTemplate | SharedAccessTemplate | GroupAccessTemplate;

Any built-in access policy template accepted by defineAccessPolicies.

GroupAccessTemplate

^type

type GroupAccessTemplate = {
  readonly kind: "group";
  readonly groups: AccessTable;
  readonly members: AccessTable;
  readonly resources: readonly AccessTable[];
  readonly groupId: string;
};

Fixed-role group, membership, and resource policy template.

GroupMembershipRow

^type

type GroupMembershipRow = Identified & { groupId: string; user_id: string; role: GroupRole; can_create: boolean; can_edit_any: boolean; can_manage: boolean };

Conventional fixed-role group membership row.

GroupOperations

^type

type GroupOperations<Group, GroupInit, Member> = {
  createGroup(values: GroupInit): Promise<{ group: Group; membership: Member }>;
  addMember(groupId: string, recipient: SharingIdentity | string, role: GroupRole): Promise<Member>;
  changeRole(groupId: string, recipient: SharingIdentity | string, role: GroupRole): Promise<Member>;
  removeMember(groupId: string, recipient: SharingIdentity | string): Promise<void>;
  leaveGroup(groupId: string): Promise<void>;
  listMembers(groupId: string): Promise<Member[]>;
};

Fixed-role group creation and membership operations.

GroupRole

^type

type GroupRole = (typeof groupRoles)[number];

Fixed group roles supported by the built-in group policy template.

Identified

^type

type Identified = {
  id: string;
};

Minimum row shape accepted by collaboration operations.

PrivateAccessTemplate

^type

type PrivateAccessTemplate = {
  readonly kind: "private";
  readonly resource: AccessTable;
};

Owner-only resource policy template.

RawAccessPolicyContext

^type

type RawAccessPolicyContext = {
  policy: Record<string, TablePolicy>;
  session: { user_id: unknown };
  allowedTo: { update(fkColumn: string): unknown };
  anyOf(conditions: readonly unknown[]): unknown;
  allOf(conditions: readonly unknown[]): unknown;
};

Raw Jazz policy-builder context exposed to advanced policy extensions.

RawAccessPolicyExtension

^type

type RawAccessPolicyExtension = (context: RawAccessPolicyContext) => void;

Callback for app-specific rules that do not fit the built-in templates.

RuleBuilder

^type

type RuleBuilder = {
  where(input: unknown): unknown;
  always(): unknown;
};

Minimal Jazz rule builder exposed to raw access-policy extensions.

SharedAccessTemplate

^type

type SharedAccessTemplate = {
  readonly kind: "shared";
  readonly resource: AccessTable;
  readonly grants: AccessTable;
};

Direct-share resource and grant-table policy template.

SharedGrantRow

^type

type SharedGrantRow = Identified & { resourceId: string; user_id: string; can_edit: boolean };

Conventional direct-share grant row.

ShareLevel

^type

type ShareLevel = "read" | "edit";

Access level assigned by a direct share.

SharingIdentity

^type

type SharingIdentity = string & { readonly __lofiSharingIdentity: true };

App-scoped, non-secret Jazz principal identifier safe to copy between users.

SharingOperations

^type

type SharingOperations<Resource, Grant> = {
  share(resourceId: string, recipient: SharingIdentity | string, level: ShareLevel): Promise<Grant>;
  revoke(resourceId: string, recipient: SharingIdentity | string): Promise<void>;
  listShares(resourceId: string): Promise<Grant[]>;
  sharedWithMe(): Promise<Resource[]>;
};

Direct-share operations bound to one resource and grant table pair.

TablePolicy

^type

type TablePolicy = {
  allowRead: RuleBuilder;
  allowInsert: RuleBuilder;
  allowUpdate: RuleBuilder;
  allowDelete: RuleBuilder;
  exists: { where(input: unknown): unknown };
};

Read and mutation policy builders for one declared table.