Peer principals and method-level Remote access control

Peer 身份属性与 Remote 方法级访问控制

A Remote method on the Host could not tell whom one call spoke for, and could not restrict callable methods by caller. The [`PeerScope`](../../../../packages/typert/protocol/src/types.ts) contract stated "Who the Peer is and what it may do are not recorded here"; [Connection](../../../../packages/client/connection/src/rpc-host.ts) had a single operator Peer, `admit()` returned it for every authenticated request, and

// @deepseek-ai/dsh-typert-protocol
export interface PeerScope {
  readonly id: PeerId
  /** Connection-lifetime registrations; disposed with the Peer. */
  readonly ctx: Context
  /** Caller identity fixed at creation by in-process Host code; no wire field can set it. */
  readonly principal: Principal
  /** Aborted once the Peer is disposed; Remote streams that speak for the Peer end with it. */
  readonly signal: AbortSignal
  /** Forwarded human-interaction participation; independent of authorization. */
  readonly interactions: 'answer' | 'none'
  dispose(): Promise<void>
}

// @deepseek-ai/dsh-client-connection
export class Peer implements PeerScope {
  constructor(owner: Context, options: { readonly principal: Principal; readonly interactions?: 'answer' | 'none' })
}

interface HostConnectionHandle {
  /** The Peer every authenticated browser connection shares; principal { kind: 'owner' }. */
  readonly browserPeer: PeerScope
  /** Network admission: the admitted Peer or the refusal status. */
  admit(request: ConnectionTrustRequest): PeerAdmission
  /** In-process only; disposed with the Context that read `ctx.connection`, or earlier by dispose(). */
  createPeer(options: { readonly principal: Principal; readonly interactions?: 'answer' | 'none' }): PeerScope
}

interface ConnectionFetchHandler {
  fetch(request: Request, peer: PeerScope): Promise<Response>
}
bridge(req, res, apiHandler, peer, maxRequestBodyBytes?)

// @deepseek-ai/dsh-api-gateway
interface InvokeRemoteRequest { …; readonly peer: PeerScope }                 // was `peer?`
wireStream.open(endpoint, payload, uplink, peer: PeerScope, signal)          // was `PeerScope | undefined`

// @deepseek-ai/dsh-typert-protocol

/**
 * Merge-extensible caller identities. Each driver declares its own entry.
 * Every entry is a JSON value with a unique literal `kind`, carries no
 * credential, and is safe to persist in a Session log.
 */
export interface PrincipalMap {
  owner: { readonly kind: 'owner' }
}
export type Principal = PrincipalMap[keyof PrincipalMap]

/**
 * @param invocation - `ctx.invocation`; `undefined` outside a Remote call.
 * @returns the caller's principal when it is not the owner; `undefined` for the
 *   owner and for trusted in-process code outside a Remote call.
 */
export function principalOf(invocation: RemoteInvocation | undefined): Principal | undefined

/** Merge-extensible resource kinds: the key is the kind, the value declares its identity type. */
export interface TypertResourceMap {}
//   @deepseek-ai/dsh-session/types:   session: TypertResource<SessionId>
//   @deepseek-ai/dsh-workspace/types: workspace: TypertResource<WorkspaceId>

// Runtime registries in typert
ctx.typert.resources.register(kind, { field }): TypertDisposer
ctx.typert.lookups.register(key, { parameter, wire, resource?, … })   // resource: the kind its wire id names
ctx.typert.contexts.registerHost(key, { wire, resource?, … })         // a TypertHostContextAdapter

export interface TypertHostContextAdapter<Wire = unknown> {
  readonly wire: string
  readonly wireTypeSymbol: string
  /** Resource kind the wire identity names; access checks read the identity from args before resolve(). */
  readonly resource?: TypertResourceKind
  resolve(id: Wire): Context | undefined | Promise<Context | undefined>
}

export type RemoteAccessResourceKind = 'global' | TypertResourceKind
export type RemoteAccessResource =
  | { readonly kind: 'global' }
  | { readonly kind: K; readonly id: TypertResourceId<TypertResourceMap[K]> }   // for each declared kind K
export type RemoteAccessResourceOf<K extends RemoteAccessResourceKind> = Extract<RemoteAccessResource, { readonly kind: K }>

/** Per-kind readers, called with the method's positional wire arguments. */
export type TypertResourceReaders<WireArgs extends readonly unknown[]> = {
  readonly [K in TypertResourceKind]?: (...args: WireArgs) => Id | readonly Id[] | undefined   // Id = TypertResourceId<TypertResourceMap[K]>
}

export interface RemoteMethodOptions<WireArgs extends unknown[]> {
  readonly name?: string
  readonly mode?: 'stream'
  readonly resources?: TypertResourceReaders<WireArgs>
}

export function Remote<This extends object, Args extends unknown[], Result>(
  option: string | RemoteMethodOptions<NoInfer<RemoteWireArgs<Args>>>,
): (method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void

export interface RemoteScopeOptions<WireArgs extends unknown[]> {
  readonly name?: string
  readonly resources?: TypertResourceReaders<WireArgs>
}

export function RemoteScope<This extends object, Args extends unknown[], Result>(
  key: Extract<keyof TypertContextMap, string>,
  option?: string | RemoteScopeOptions<NoInfer<RemoteWireArgs<Args>>>,
): (method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void

/** Remote endpoint `ns/method`, or `event:<name>` for one forwarded event; endpoint segments never contain `:`. */
export type RemoteAccessAction = RemoteAccessEndpoint | `event:${string}`

/** A named action set over one resource kind; a plain value owned by the business package. */
export interface RemoteAccessRole<K extends RemoteAccessResourceKind> {
  readonly name: string
  readonly resource: K
  readonly actions: readonly RemoteAccessAction[]
}

/** Answer of decide() and of a condition. */
export type RemoteAccessDecision =
  | { readonly kind: 'allow' }
  | { readonly kind: 'deny'; readonly reason: string }

/** Refines one binding for one action on its resource; `args` only for a concrete call. */
export type RemoteAccessCondition<K extends RemoteAccessResourceKind> = (request: {
  readonly action: RemoteAccessAction
  readonly resource: RemoteAccessResourceOf<K>
  readonly args?: Readonly<Record<string, unknown>>
}) => RemoteAccessDecision

/** One role on one resource of the role's kind; the resource type follows from the role. */
export type RemoteAccessBinding = {
  [K in RemoteAccessResourceKind]: {
    readonly role: RemoteAccessRole<K>
    readonly resource: RemoteAccessResourceOf<K>
    readonly condition?: RemoteAccessCondition<K>
  }
}[RemoteAccessResourceKind]

/** One access question; the Gateway passes only valid resources, [global] when none. */
export interface RemoteAccessRequest<P extends Principal> {
  readonly principal: P
  readonly action: RemoteAccessAction
  /** Allow only when the action is allowed on every listed resource. */
  readonly resources: readonly RemoteAccessResource[]
  /** Named arguments of a concrete call, validated against their Typert-compiled types with lookup parameters as wire identities; absent for events, snapshots, and list filtering. */
  readonly args?: Readonly<Record<string, unknown>>
}

/** Business rules for one non-owner principal kind; synchronous over in-memory state. */
export interface RemoteAccessPolicy<P extends Principal> {
  bindings(principal: P): readonly RemoteAccessBinding[]
  /** Reason for a request no binding allows; never changes the decision. */
  explain?(request: RemoteAccessRequest<P>): string | undefined
}

/** details of `remote-access/denied` */
export interface RemoteAccessDeniedDetails {
  readonly action: string
  readonly reason: string
}

class RemoteAccessService {            // ctx.remoteAccess; Remote namespace remoteAccess
  registerPolicy<K extends Exclude<keyof PrincipalMap, 'owner'>>(kind: K, policy: RemoteAccessPolicy<PrincipalMap[K]>): () => void
  invalidate(principal?: Principal): void
  decide(request: RemoteAccessRequest<Principal>): RemoteAccessDecision   // Gateway-only
  allows(resource: RemoteAccessResource): boolean              // reads the accessing ctx's invocation
  snapshotFor(principal: Principal): RemoteAccessBaseline      // a page's opening baseline
  follow(signal): AsyncIterable<RemoteAccessFrame>             // remoteAccess/follow
}

const globalReader    = { name: 'share:global-reader',    resource: 'global',    actions: ['session/list', 'session/control', 'workspace/follow', 'session/modelCatalog', 'llm/listProviders', 'commands/list'] }
const sessionReader   = { name: 'share:session-reader',   resource: 'session',   actions: ['session/page', 'session/follow', 'session/list', 'session/control', 'workspace/follow', 'commands/list', 'event:api-session/status', 'event:api-session/added'] }
const workspaceReader = { name: 'share:workspace-reader', resource: 'workspace', actions: ['workspace/follow'] }
const forker          = { name: 'share:forker',           resource: 'session',   actions: ['session/fork'] }
const writer          = { name: 'share:writer',           resource: 'session',   actions: ['session/prompt', 'session/cancel'] }

ctx.effect(() => ctx.remoteAccess.registerPolicy('share-viewer', {
  bindings(viewer) {
    const share = shares.serving(viewer)              // undefined once stopped, expired, or no longer admitted
    if (share === undefined) return []
    const source = { kind: 'session', id: share.sessionId }
    return [
      { role: globalReader, resource: { kind: 'global' } },
      { role: sessionReader, resource: source },
      ...(share.allowsFork ? [{ role: forker, resource: source }] : []),
      ...(share.mode === 'write' ? [{ role: writer, resource: source, condition: sourceWrite(share) }] : []),
      ...shares.forksOf(viewer).flatMap(child => [
        { role: sessionReader, resource: { kind: 'session', id: child.id } },
        ...(child.revoked ? [] : [{ role: writer, resource: { kind: 'session', id: child.id }, condition: childPrompt(child) }]),
      ]),
      ...shares.workspacesShowing(viewer).map(id => ({ role: workspaceReader, resource: { kind: 'workspace', id } })),
    ]
  },
  explain({ principal, action }) {
    return shares.refusal(principal)                  // 'share-expired', 'share-stopped', …
      ?? (action === 'session/prompt' ? 'share-not-writable' : undefined)
  },
}))

// Without args (snapshots, list filtering) a condition answers for the action alone.
const sourceWrite = share => () => share.confined ? allow : deny('source-write-unavailable')
const childPrompt = child => ({ action, args }) =>
  action === 'session/prompt' && args !== undefined && !child.allowsPrompt() ? deny('fork-prompt-refused') : allow

// Remote: remoteAccess/follow (stream; every Peer may read its own snapshot)
type RemoteAccessFrame =
  | { readonly type: 'baseline'; readonly owner: true }
  | { readonly type: 'baseline'; readonly owner: false; readonly grants: readonly RemoteAccessGrant[] }
  | { readonly type: 'upsert'; readonly grant: RemoteAccessGrant }
  | { readonly type: 'remove'; readonly resource: RemoteAccessResource }

interface RemoteAccessGrant {
  readonly resource: RemoteAccessResource    // global, or one declared-kind resource
  readonly actions: readonly string[]        // endpoint actions allowed on this resource without args, sorted
}

/** Window global carrying a page's opening baseline. */
export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'

// @deepseek-ai/dsh-api-remote-access/client
interface ClientRemoteAccess {            // Client service ctx.remoteAccess
  source(kind: TypertResourceKind, id: string, action: string): HostObservable<boolean>
}
GlobalStandardProps.useRemoteAccess: (action: RemoteEndpoint) => boolean                  // remote-access; the global resource

// @deepseek-ai/dsh-client-ui-session (injects remoteAccess)
GlobalStandardProps.useSessionAccess: (sessionId: SessionId, action: RemoteEndpoint) => boolean
SessionStandardProps.useAccess: (action: RemoteEndpoint) => boolean
SessionMaybeStandardProps.useAccess: (action: RemoteEndpoint) => boolean | undefined

// @deepseek-ai/dsh-client-ui-workspace (injects remoteAccess)
GlobalStandardProps.useWorkspaceAccess: (workspaceId: WorkspaceId, action: RemoteEndpoint) => boolean

// RemoteEndpoint = Extract<keyof TypertRemoteMap, string>

'user-rpc': {
  kind: 'user'
  rpcId: SessionRequestId
  clientTimeZone?: string
  /** Non-owner caller that submitted this prompt; absent means the owner. */
  principal?: Principal
}

// @deepseek-ai/dsh-typert-protocol
export interface PeerScope {
  readonly id: PeerId
  /** Connection-lifetime registrations; disposed with the Peer. */
  readonly ctx: Context
  /** Caller identity fixed at creation by in-process Host code; no wire field can set it. */
  readonly principal: Principal
  /** Aborted once the Peer is disposed; Remote streams that speak for the Peer end with it. */
  readonly signal: AbortSignal
  /** Forwarded human-interaction participation; independent of authorization. */
  readonly interactions: 'answer' | 'none'
  dispose(): Promise<void>
}

// @deepseek-ai/dsh-client-connection
export class Peer implements PeerScope {
  constructor(owner: Context, options: { readonly principal: Principal; readonly interactions?: 'answer' | 'none' })
}

interface HostConnectionHandle {
  /** The Peer every authenticated browser connection shares; principal { kind: 'owner' }. */
  readonly browserPeer: PeerScope
  /** Network admission: the admitted Peer or the refusal status. */
  admit(request: ConnectionTrustRequest): PeerAdmission
  /** In-process only; disposed with the Context that read `ctx.connection`, or earlier by dispose(). */
  createPeer(options: { readonly principal: Principal; readonly interactions?: 'answer' | 'none' }): PeerScope
}

interface ConnectionFetchHandler {
  fetch(request: Request, peer: PeerScope): Promise<Response>
}
bridge(req, res, apiHandler, peer, maxRequestBodyBytes?)

// @deepseek-ai/dsh-api-gateway
interface InvokeRemoteRequest { …; readonly peer: PeerScope }                 // was `peer?`
wireStream.open(endpoint, payload, uplink, peer: PeerScope, signal)          // was `PeerScope | undefined`

// @deepseek-ai/dsh-typert-protocol

/**
 * Merge-extensible caller identities. Each driver declares its own entry.
 * Every entry is a JSON value with a unique literal `kind`, carries no
 * credential, and is safe to persist in a Session log.
 */
export interface PrincipalMap {
  owner: { readonly kind: 'owner' }
}
export type Principal = PrincipalMap[keyof PrincipalMap]

/**
 * @param invocation - `ctx.invocation`; `undefined` outside a Remote call.
 * @returns the caller's principal when it is not the owner; `undefined` for the
 *   owner and for trusted in-process code outside a Remote call.
 */
export function principalOf(invocation: RemoteInvocation | undefined): Principal | undefined

/** Merge-extensible resource kinds: the key is the kind, the value declares its identity type. */
export interface TypertResourceMap {}
//   @deepseek-ai/dsh-session/types:   session: TypertResource<SessionId>
//   @deepseek-ai/dsh-workspace/types: workspace: TypertResource<WorkspaceId>

// Runtime registries in typert
ctx.typert.resources.register(kind, { field }): TypertDisposer
ctx.typert.lookups.register(key, { parameter, wire, resource?, … })   // resource: the kind its wire id names
ctx.typert.contexts.registerHost(key, { wire, resource?, … })         // a TypertHostContextAdapter

export interface TypertHostContextAdapter<Wire = unknown> {
  readonly wire: string
  readonly wireTypeSymbol: string
  /** Resource kind the wire identity names; access checks read the identity from args before resolve(). */
  readonly resource?: TypertResourceKind
  resolve(id: Wire): Context | undefined | Promise<Context | undefined>
}

export type RemoteAccessResourceKind = 'global' | TypertResourceKind
export type RemoteAccessResource =
  | { readonly kind: 'global' }
  | { readonly kind: K; readonly id: TypertResourceId<TypertResourceMap[K]> }   // for each declared kind K
export type RemoteAccessResourceOf<K extends RemoteAccessResourceKind> = Extract<RemoteAccessResource, { readonly kind: K }>

/** Per-kind readers, called with the method's positional wire arguments. */
export type TypertResourceReaders<WireArgs extends readonly unknown[]> = {
  readonly [K in TypertResourceKind]?: (...args: WireArgs) => Id | readonly Id[] | undefined   // Id = TypertResourceId<TypertResourceMap[K]>
}

export interface RemoteMethodOptions<WireArgs extends unknown[]> {
  readonly name?: string
  readonly mode?: 'stream'
  readonly resources?: TypertResourceReaders<WireArgs>
}

export function Remote<This extends object, Args extends unknown[], Result>(
  option: string | RemoteMethodOptions<NoInfer<RemoteWireArgs<Args>>>,
): (method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void

export interface RemoteScopeOptions<WireArgs extends unknown[]> {
  readonly name?: string
  readonly resources?: TypertResourceReaders<WireArgs>
}

export function RemoteScope<This extends object, Args extends unknown[], Result>(
  key: Extract<keyof TypertContextMap, string>,
  option?: string | RemoteScopeOptions<NoInfer<RemoteWireArgs<Args>>>,
): (method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void

/** Remote endpoint `ns/method`, or `event:<name>` for one forwarded event; endpoint segments never contain `:`. */
export type RemoteAccessAction = RemoteAccessEndpoint | `event:${string}`

/** A named action set over one resource kind; a plain value owned by the business package. */
export interface RemoteAccessRole<K extends RemoteAccessResourceKind> {
  readonly name: string
  readonly resource: K
  readonly actions: readonly RemoteAccessAction[]
}

/** Answer of decide() and of a condition. */
export type RemoteAccessDecision =
  | { readonly kind: 'allow' }
  | { readonly kind: 'deny'; readonly reason: string }

/** Refines one binding for one action on its resource; `args` only for a concrete call. */
export type RemoteAccessCondition<K extends RemoteAccessResourceKind> = (request: {
  readonly action: RemoteAccessAction
  readonly resource: RemoteAccessResourceOf<K>
  readonly args?: Readonly<Record<string, unknown>>
}) => RemoteAccessDecision

/** One role on one resource of the role's kind; the resource type follows from the role. */
export type RemoteAccessBinding = {
  [K in RemoteAccessResourceKind]: {
    readonly role: RemoteAccessRole<K>
    readonly resource: RemoteAccessResourceOf<K>
    readonly condition?: RemoteAccessCondition<K>
  }
}[RemoteAccessResourceKind]

/** One access question; the Gateway passes only valid resources, [global] when none. */
export interface RemoteAccessRequest<P extends Principal> {
  readonly principal: P
  readonly action: RemoteAccessAction
  /** Allow only when the action is allowed on every listed resource. */
  readonly resources: readonly RemoteAccessResource[]
  /** Named arguments of a concrete call, validated against their Typert-compiled types with lookup parameters as wire identities; absent for events, snapshots, and list filtering. */
  readonly args?: Readonly<Record<string, unknown>>
}

/** Business rules for one non-owner principal kind; synchronous over in-memory state. */
export interface RemoteAccessPolicy<P extends Principal> {
  bindings(principal: P): readonly RemoteAccessBinding[]
  /** Reason for a request no binding allows; never changes the decision. */
  explain?(request: RemoteAccessRequest<P>): string | undefined
}

/** details of `remote-access/denied` */
export interface RemoteAccessDeniedDetails {
  readonly action: string
  readonly reason: string
}

class RemoteAccessService {            // ctx.remoteAccess; Remote namespace remoteAccess
  registerPolicy<K extends Exclude<keyof PrincipalMap, 'owner'>>(kind: K, policy: RemoteAccessPolicy<PrincipalMap[K]>): () => void
  invalidate(principal?: Principal): void
  decide(request: RemoteAccessRequest<Principal>): RemoteAccessDecision   // Gateway-only
  allows(resource: RemoteAccessResource): boolean              // reads the accessing ctx's invocation
  snapshotFor(principal: Principal): RemoteAccessBaseline      // a page's opening baseline
  follow(signal): AsyncIterable<RemoteAccessFrame>             // remoteAccess/follow
}

const globalReader    = { name: 'share:global-reader',    resource: 'global',    actions: ['session/list', 'session/control', 'workspace/follow', 'session/modelCatalog', 'llm/listProviders', 'commands/list'] }
const sessionReader   = { name: 'share:session-reader',   resource: 'session',   actions: ['session/page', 'session/follow', 'session/list', 'session/control', 'workspace/follow', 'commands/list', 'event:api-session/status', 'event:api-session/added'] }
const workspaceReader = { name: 'share:workspace-reader', resource: 'workspace', actions: ['workspace/follow'] }
const forker          = { name: 'share:forker',           resource: 'session',   actions: ['session/fork'] }
const writer          = { name: 'share:writer',           resource: 'session',   actions: ['session/prompt', 'session/cancel'] }

ctx.effect(() => ctx.remoteAccess.registerPolicy('share-viewer', {
  bindings(viewer) {
    const share = shares.serving(viewer)              // undefined once stopped, expired, or no longer admitted
    if (share === undefined) return []
    const source = { kind: 'session', id: share.sessionId }
    return [
      { role: globalReader, resource: { kind: 'global' } },
      { role: sessionReader, resource: source },
      ...(share.allowsFork ? [{ role: forker, resource: source }] : []),
      ...(share.mode === 'write' ? [{ role: writer, resource: source, condition: sourceWrite(share) }] : []),
      ...shares.forksOf(viewer).flatMap(child => [
        { role: sessionReader, resource: { kind: 'session', id: child.id } },
        ...(child.revoked ? [] : [{ role: writer, resource: { kind: 'session', id: child.id }, condition: childPrompt(child) }]),
      ]),
      ...shares.workspacesShowing(viewer).map(id => ({ role: workspaceReader, resource: { kind: 'workspace', id } })),
    ]
  },
  explain({ principal, action }) {
    return shares.refusal(principal)                  // 'share-expired', 'share-stopped', …
      ?? (action === 'session/prompt' ? 'share-not-writable' : undefined)
  },
}))

// Without args (snapshots, list filtering) a condition answers for the action alone.
const sourceWrite = share => () => share.confined ? allow : deny('source-write-unavailable')
const childPrompt = child => ({ action, args }) =>
  action === 'session/prompt' && args !== undefined && !child.allowsPrompt() ? deny('fork-prompt-refused') : allow

// Remote: remoteAccess/follow (stream; every Peer may read its own snapshot)
type RemoteAccessFrame =
  | { readonly type: 'baseline'; readonly owner: true }
  | { readonly type: 'baseline'; readonly owner: false; readonly grants: readonly RemoteAccessGrant[] }
  | { readonly type: 'upsert'; readonly grant: RemoteAccessGrant }
  | { readonly type: 'remove'; readonly resource: RemoteAccessResource }

interface RemoteAccessGrant {
  readonly resource: RemoteAccessResource    // global, or one declared-kind resource
  readonly actions: readonly string[]        // endpoint actions allowed on this resource without args, sorted
}

/** Window global carrying a page's opening baseline. */
export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'

// @deepseek-ai/dsh-api-remote-access/client
interface ClientRemoteAccess {            // Client service ctx.remoteAccess
  source(kind: TypertResourceKind, id: string, action: string): HostObservable<boolean>
}
GlobalStandardProps.useRemoteAccess: (action: RemoteEndpoint) => boolean                  // remote-access; the global resource

// @deepseek-ai/dsh-client-ui-session (injects remoteAccess)
GlobalStandardProps.useSessionAccess: (sessionId: SessionId, action: RemoteEndpoint) => boolean
SessionStandardProps.useAccess: (action: RemoteEndpoint) => boolean
SessionMaybeStandardProps.useAccess: (action: RemoteEndpoint) => boolean | undefined

// @deepseek-ai/dsh-client-ui-workspace (injects remoteAccess)
GlobalStandardProps.useWorkspaceAccess: (workspaceId: WorkspaceId, action: RemoteEndpoint) => boolean

// RemoteEndpoint = Extract<keyof TypertRemoteMap, string>

'user-rpc': {
  kind: 'user'
  rpcId: SessionRequestId
  clientTimeZone?: string
  /** Non-owner caller that submitted this prompt; absent means the owner. */
  principal?: Principal
}