@openagentid/scim API

export declare const createScimRouter: (routerConfig?: ScimRouterConfig) => ScimRouter;

export interface ScimRouter {
    /** Handle a WHATWG Request and return a WHATWG Response. */
    handle(request: Request): Promise<Response>;
}

// ── Router configuration ──────────────────────────────────────────────────
export interface ScimRouterConfig extends ScimBridgeConfig {
    /** Custom agent store. Defaults to in-memory. */
    readonly store?: AgentStore;
    /** Audit event sink. */
    readonly auditSink?: AuditSink;
    /** DID revocation hook (production: OAS SDK). */
    readonly revokeDidDocument?: DidRevoker;
    /** Delegation cascade revocation hook (production: AEGIS SDK). */
    readonly cascadeRevokeDelegations?: DelegationCascadeRevoker;
    /** Arsenal session invalidation hook (production: Arsenal SDK). */
    readonly invalidateArsenalSessions?: ArsenalSessionInvalidator;
}

/** Configuration for the SCIM provisioning bridge. */
export interface ScimBridgeConfig {
    /**
     * OAS namespace for generated DIDs. Defaults to `l1fe`.
     */
    readonly namespace?: string;
    /**
     * Bearer token(s) that SCIM clients must present.
     * When undefined, authentication is disabled (dev only).
     */
    readonly bearerTokens?: readonly string[];
    /**
     * Base URL for SCIM resource `meta.location` fields.
     * Example: `https://scim.example.com/scim/v2`
     */
    readonly baseUrl?: string;
    /** Maximum page size for list responses. Default: 100. */
    readonly maxPageSize?: number;
    /** Structured logger. */
    readonly logger?: Logger;
}

export interface ResolvedScimConfig {
    readonly namespace: string;
    readonly bearerTokens: readonly string[];
    readonly baseUrl: string;
    readonly maxPageSize: number;
    readonly logger: Logger;
}

/** Logger interface matching the OpenAgent SDK convention. */
export interface Logger {
    debug(msg: string, fields?: Record<string, unknown>): void;
    info(msg: string, fields?: Record<string, unknown>): void;
    warn(msg: string, fields?: Record<string, unknown>): void;
    error(msg: string, fields?: Record<string, unknown>): void;
}

export declare const resolveScimConfig: (config?: ScimBridgeConfig) => ResolvedScimConfig;

export declare const silentLogger: Logger;

export declare const SCIM_USER_SCHEMA: "urn:ietf:params:scim:schemas:core:2.0:User";

export declare const OPENAGENT_AGENT_SCHEMA: "urn:openagent:scim:1.0:Agent";

export declare const SCIM_LIST_RESPONSE_SCHEMA: "urn:ietf:params:scim:api:messages:2.0:ListResponse";

export declare const SCIM_ERROR_SCHEMA: "urn:ietf:params:scim:api:messages:2.0:Error";

export declare const SCIM_PATCH_OP_SCHEMA: "urn:ietf:params:scim:api:messages:2.0:PatchOp";

export declare const SCIM_SPC_SCHEMA: "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig";

export declare const SCIM_SCHEMA_SCHEMA: "urn:ietf:params:scim:schemas:core:2.0:Schema";

export declare const SCIM_RESOURCE_TYPE_SCHEMA: "urn:ietf:params:scim:schemas:core:2.0:ResourceType";

/** Conformance levels for OpenAgent agents. */
export type ConformanceLevel = 'L0' | 'L1' | 'L2';

/** The OpenAgent agent extension attribute group. */
export interface AgentExtension {
    readonly parentDid: string;
    readonly conformanceLevel: ConformanceLevel;
    readonly scopes: readonly string[];
    readonly lineageDepth: number;
    readonly createdVia: string;
    readonly keypairFingerprint: string;
}

/** Full SCIM User resource with agent extension. */
export interface ScimAgentResource {
    readonly schemas: readonly string[];
    readonly id: string;
    readonly externalId?: string;
    readonly userName: string;
    readonly displayName: string;
    readonly active: boolean;
    readonly meta: ScimMeta;
    readonly [OPENAGENT_AGENT_SCHEMA]: AgentExtension;
}

/** SCIM resource metadata. */
export interface ScimMeta {
    readonly resourceType: string;
    readonly created: string;
    readonly lastModified: string;
    readonly location: string;
    readonly version: string;
}

/** SCIM List Response envelope. */
export interface ScimListResponse<T> {
    readonly schemas: readonly string[];
    readonly totalResults: number;
    readonly startIndex: number;
    readonly itemsPerPage: number;
    readonly Resources: readonly T[];
}

/** SCIM Error response. */
export interface ScimErrorResponse {
    readonly schemas: readonly string[];
    readonly status: string;
    readonly scimType?: string;
    readonly detail: string;
}

export declare const buildServiceProviderConfig: (baseUrl: string) => Record<string, unknown>;

export declare const buildSchemas: () => readonly Record<string, unknown>[];

export declare const buildResourceTypes: (baseUrl: string) => readonly Record<string, unknown>[];

// ── Internal agent record ─────────────────────────────────────────────────
/** The canonical internal representation of a provisioned agent. */
export interface AgentRecord {
    readonly did: string;
    readonly userName: string;
    readonly displayName: string;
    readonly active: boolean;
    readonly parentDid: string;
    readonly conformanceLevel: ConformanceLevel;
    readonly scopes: readonly string[];
    readonly lineageDepth: number;
    readonly createdVia: string;
    readonly keypairFingerprint: string;
    readonly createdAt: string;
    readonly updatedAt: string;
    readonly version: string;
    readonly externalId?: string;
}

export type CreateAgentFromScimInput = z.infer<typeof createAgentFromScimSchema>;

export type ReplaceAgentFromScimInput = z.infer<typeof replaceAgentFromScimSchema>;

export declare const agentToScimResource: (agent: AgentRecord, baseUrl: string) => ScimAgentResource;

export declare const parseCreateInput: (body: unknown) => CreateAgentFromScimInput;

export declare const parseReplaceInput: (body: unknown) => ReplaceAgentFromScimInput;

export declare const createAgentFromScimSchema: z.ZodObject<{ schemas: z.ZodArray<z.ZodString>; externalId: z.ZodOptional<z.ZodString>; userName: z.ZodString; displayName: z.ZodOptional<z.ZodString>; active: z.ZodDefault<z.ZodBoolean>; "urn:openagent:scim:1.0:Agent": z.ZodObject<{ parentDid: z.ZodString; conformanceLevel: z.ZodDefault<z.ZodEnum<{ L0: "L0"; L1: "L1"; L2: "L2"; }>>; scopes: z.ZodArray<z.ZodString>; lineageDepth: z.ZodOptional<z.ZodNumber>; createdVia: z.ZodOptional<z.ZodString>; keypairFingerprint: z.ZodOptional<z.ZodString>; }, z.core.$strip>; }, z.core.$strip>;

export type ParsedFilter = AttributeFilter | LogicalFilter;

/** A single attribute filter expression. */
export interface AttributeFilter {
    readonly type: 'attribute';
    readonly attribute: string;
    readonly op: FilterOp;
    readonly value: string | boolean | number | null;
}

/** Logical combination of filters. */
export interface LogicalFilter {
    readonly type: 'and' | 'or';
    readonly filters: readonly ParsedFilter[];
}

/** Supported comparison operators. */
export type FilterOp = 'eq' | 'ne' | 'co' | 'sw' | 'ew' | 'pr' | 'gt' | 'ge' | 'lt' | 'le';

export declare const parseFilter: (filterStr: string | undefined | null) => ParsedFilter | undefined;

export declare const matchesFilter: (record: AgentRecord, filter: ParsedFilter | undefined) => boolean;

export declare class ScimFilterError {
  constructor(message: string): ScimFilterError;
}

/** Parsed pagination parameters from a SCIM request. */
export interface PaginationParams {
    /** 1-based start index. */
    readonly startIndex: number;
    /** Number of results to return. */
    readonly count: number;
}

export declare const parsePagination: (searchParams: URLSearchParams, maxPageSize: number) => PaginationParams;

export declare const paginateResults: <T>(items: readonly T[], params: PaginationParams) => ScimListResponse<T>;

/** A single SCIM PATCH operation. */
export interface PatchOperation {
    readonly op: 'add' | 'replace' | 'remove';
    readonly path?: string;
    readonly value?: unknown;
}

/** SCIM PatchOp request body. */
export interface PatchRequest {
    readonly schemas: readonly string[];
    readonly Operations: readonly PatchOperation[];
}

export declare const parsePatchRequest: (body: unknown) => PatchRequest;

export declare const applyPatchOperations: (record: AgentRecord, operations: readonly PatchOperation[]) => AgentRecord;

export declare class ScimPatchError {
  constructor(message: string): ScimPatchError;
}

export declare class AgentProvisioner {
  constructor(config: ProvisionerConfig): AgentProvisioner;
  createAgent(params: CreateAgentParams): Promise<AgentRecord>;
  replaceAgent(did: string, params: CreateAgentParams): Promise<AgentRecord>;
  updateAgent(did: string, record: AgentRecord): Promise<AgentRecord>;
  deprovisionAgent(did: string): Promise<void>;
  findByDid(did: string): Promise<AgentRecord | undefined>;
  findByUserName(userName: string): Promise<AgentRecord | undefined>;
  listAgents(): Promise<readonly AgentRecord[]>;
}

// ── Provisioner configuration ─────────────────────────────────────────────
export interface ProvisionerConfig {
    readonly store: AgentStore;
    readonly namespace: string;
    readonly logger: Logger;
    readonly auditSink?: AuditSink;
    readonly revokeDidDocument?: DidRevoker;
    readonly cascadeRevokeDelegations?: DelegationCascadeRevoker;
    readonly invalidateArsenalSessions?: ArsenalSessionInvalidator;
}

// ── Create ────────────────────────────────────────────────────────────────
export interface CreateAgentParams {
    readonly userName: string;
    readonly displayName?: string;
    readonly parentDid: string;
    readonly conformanceLevel: ConformanceLevel;
    readonly scopes: readonly string[];
    readonly externalId?: string;
}

// ── Event types ───────────────────────────────────────────────────────────
/** Audit event emitted during agent lifecycle operations. */
export interface AuditEvent {
    readonly type: 'agent.created' | 'agent.updated' | 'agent.deprovisioned';
    readonly did: string;
    readonly timestamp: string;
    readonly details: Record<string, unknown>;
}

/** Callback invoked for each lifecycle audit event. */
export type AuditSink = (event: AuditEvent) => void | Promise<void>;

// ── Deprovisioning hooks ──────────────────────────────────────────────────
/**
 * Hook invoked during deprovisioning to revoke the agent's DID document.
 *
 * Production: wires to OAS SDK's `revokeIdentity`.
 * Default: no-op (logs a warning).
 */
export type DidRevoker = (did: string) => Promise<void>;

/**
 * Hook invoked during deprovisioning to cascade-revoke all delegation
 * proofs issued by (or to) the deprovisioned agent.
 *
 * Production: wires to AEGIS SDK's delegation tree walker.
 * Default: no-op (logs a warning).
 */
export type DelegationCascadeRevoker = (did: string) => Promise<void>;

/**
 * Hook invoked during deprovisioning to invalidate all active Arsenal
 * sessions for the deprovisioned agent.
 *
 * Production: wires to Arsenal SDK's session invalidation.
 * Default: no-op (logs a warning).
 */
export type ArsenalSessionInvalidator = (did: string) => Promise<void>;

export declare class ProvisionerError {
  code: ProvisionerErrorCode;
  constructor(message: string, code: ProvisionerErrorCode): ProvisionerError;
}

/**
 * Storage interface for agent records.
 *
 * All methods return new objects — implementations must never return
 * mutable references to internal state.
 */
export interface AgentStore {
    /** List all agent records. Returns an immutable snapshot. */
    list(): Promise<readonly AgentRecord[]>;
    /** Find agent by DID. Returns undefined if not found. */
    findByDid(did: string): Promise<AgentRecord | undefined>;
    /** Find agent by userName. Returns undefined if not found. */
    findByUserName(userName: string): Promise<AgentRecord | undefined>;
    /** Find agent by externalId. Returns undefined if not found. */
    findByExternalId(externalId: string): Promise<AgentRecord | undefined>;
    /** Insert a new agent record. Throws if DID already exists. */
    create(record: AgentRecord): Promise<AgentRecord>;
    /** Replace an agent record. Throws if DID does not exist. */
    update(did: string, record: AgentRecord): Promise<AgentRecord>;
    /** Delete an agent record. Throws if DID does not exist. */
    delete(did: string): Promise<void>;
    /** Return the count of all active agents. */
    countActive(): Promise<number>;
}

export declare class InMemoryAgentStore {
  list(): Promise<readonly AgentRecord[]>;
  findByDid(did: string): Promise<AgentRecord | undefined>;
  findByUserName(userName: string): Promise<AgentRecord | undefined>;
  findByExternalId(externalId: string): Promise<AgentRecord | undefined>;
  create(record: AgentRecord): Promise<AgentRecord>;
  update(did: string, record: AgentRecord): Promise<AgentRecord>;
  delete(did: string): Promise<void>;
  countActive(): Promise<number>;
}

export declare class StoreError {
  code: StoreErrorCode;
  constructor(message: string, code: StoreErrorCode): StoreError;
}

export type StoreErrorCode = 'NOT_FOUND' | 'CONFLICT' | 'INTERNAL';

export declare const VERSION: "0.1.1";