@stryke/capnp/schemas/persistent.d.mts

A package to assist in running the Cap'n Proto compiler and creating Cap'n Proto serialization protocol schemas.

import { c as Orphan, d as Server, f as Struct, i as Interface, l as PipelineOp, n as Call, p as StructCtor, r as Client, s as Method, t as Answer, u as Pointer } from "./index-ovAGvA_u.mjs";

//#region ../../node_modules/.pnpm/capnp-es@0.0.11_patch_hash=503a440bd2bef41c0cb22819bc4ced5a7f04993fb999f0d944e284220f14916b_typescript@6.0.3/node_modules/capnp-es/dist/shared/capnp-es.CMmWj66v.d.mts
/**
 * PipelineClient implements Client by calling to the pipeline's answer.
 */
declare class PipelineClient<AnswerResults extends Struct, ParentResults extends Struct, Results extends Struct> implements Client {
  pipeline: Pipeline<AnswerResults, ParentResults, Results>;
  constructor(pipeline: Pipeline<AnswerResults, ParentResults, Results>);
  transform(): PipelineOp[];
  call<CallParams extends Struct, CallResults extends Struct>(call: Call<CallParams, CallResults>): Answer<CallResults>;
  close(): void;
}
/**
 * A Pipeline is a generic wrapper for an answer
 */
declare class Pipeline<AnswerResults extends Struct, ParentResults extends Struct, Results extends Struct> {
  ResultsClass: StructCtor<Results>;
  answer: Answer<AnswerResults>;
  parent?: Pipeline<AnswerResults, Struct, ParentResults> | undefined;
  op: PipelineOp;
  pipelineClient?: PipelineClient<AnswerResults, ParentResults, Results>;
  constructor(ResultsClass: StructCtor<Results>, answer: Answer<AnswerResults>, op?: PipelineOp, parent?: Pipeline<AnswerResults, Struct, ParentResults> | undefined);
  transform(): PipelineOp[];
  struct(): Promise<Results>;
  client(): PipelineClient<AnswerResults, ParentResults, Results>;
  getPipeline<RR extends Struct>(ResultsClass: StructCtor<RR>, off: number, defaultValue?: Pointer): Pipeline<AnswerResults, Results, RR>;
}
//#endregion
//#region schemas/persistent.d.ts
declare const _capnpFileId: bigint;
declare class Persistent_SaveParams extends Struct {
  static readonly _capnp: {
    displayName: string;
    id: string;
    size: any;
  };
  _adoptSealFor(value: Orphan<Pointer>): void;
  _disownSealFor(): Orphan<Pointer>;
  /**
  * Seal the SturdyRef so that it can only be restored by the specified Owner. This is meant
  * to mitigate damage when a SturdyRef is leaked. See comments above.
  *
  * Leaving this value null may or may not be allowed; it is up to the realm to decide. If a
  * realm does allow a null owner, this should indicate that anyone is allowed to restore the
  * ref.
  *
  */
  get sealFor(): Pointer;
  _hasSealFor(): boolean;
  set sealFor(value: Pointer);
  toString(): string;
}
declare class Persistent_SaveResults extends Struct {
  static readonly _capnp: {
    displayName: string;
    id: string;
    size: any;
  };
  _adoptSturdyRef(value: Orphan<Pointer>): void;
  _disownSturdyRef(): Orphan<Pointer>;
  get sturdyRef(): Pointer;
  _hasSturdyRef(): boolean;
  set sturdyRef(value: Pointer);
  toString(): string;
}
declare class Persistent_SaveResults$Promise {
  pipeline: Pipeline<any, any, Persistent_SaveResults>;
  constructor(pipeline: Pipeline<any, any, Persistent_SaveResults>);
  promise(): Promise<Persistent_SaveResults>;
}
declare class Persistent$Client {
  client: Client;
  static readonly interfaceId: bigint;
  constructor(client: Client);
  static readonly methods: [Method<Persistent_SaveParams, Persistent_SaveResults>];
  /**
  * Save a capability persistently so that it can be restored by a future connection.  Not all
  * capabilities can be saved -- application interfaces should define which capabilities support
  * this and which do not.
  *
  */
  save(paramsFunc?: (params: Persistent_SaveParams) => void): Persistent_SaveResults$Promise;
}
interface Persistent$Server$Target {
  save(params: Persistent_SaveParams, results: Persistent_SaveResults): Promise<void>;
}
declare class Persistent$Server extends Server {
  readonly target: Persistent$Server$Target;
  constructor(target: Persistent$Server$Target);
  client(): Persistent$Client;
}
/**
* Interface implemented by capabilities that outlive a single connection. A client may save()
* the capability, producing a SturdyRef. The SturdyRef can be stored to disk, then later used to
* obtain a new reference to the capability on a future connection.
*
* The exact format of SturdyRef depends on the "realm" in which the SturdyRef appears. A "realm"
* is an abstract space in which all SturdyRefs have the same format and refer to the same set of
* resources. Every vat is in exactly one realm. All capability clients within that vat must
* produce SturdyRefs of the format appropriate for the realm.
*
* Similarly, every VatNetwork also resides in a particular realm. Usually, a vat's "realm"
* corresponds to the realm of its main VatNetwork. However, a Vat can in fact communicate over
* a VatNetwork in a different realm -- in this case, all SturdyRefs need to be transformed when
* coming or going through said VatNetwork. The RPC system has hooks for registering
* transformation callbacks for this purpose.
*
* Since the format of SturdyRef is realm-dependent, it is not defined here. An application should
* choose an appropriate realm for itself as part of its design. Note that under Sandstorm, every
* application exists in its own realm and is therefore free to define its own SturdyRef format;
* the Sandstorm platform handles translating between realms.
*
* Note that whether a capability is persistent is often orthogonal to its type. In these cases,
* the capability's interface should NOT inherit `Persistent`; instead, just perform a cast at
* runtime. It's not type-safe, but trying to be type-safe in these cases will likely lead to
* tears. In cases where a particular interface only makes sense on persistent capabilities, it
* still should not explicitly inherit Persistent because the `SturdyRef` and `Owner` types will
* vary between realms (they may even be different at the call site than they are on the
* implementation). Instead, mark persistent interfaces with the $persistent annotation (defined
* below).
*
* Sealing
* -------
*
* As an added security measure, SturdyRefs may be "sealed" to a particular owner, such that
* if the SturdyRef itself leaks to a third party, that party cannot actually restore it because
* they are not the owner. To restore a sealed capability, you must first prove to its host that
* you are the rightful owner. The precise mechanism for this authentication is defined by the
* realm.
*
* Sealing is a defense-in-depth mechanism meant to mitigate damage in the case of catastrophic
* attacks. For example, say an attacker temporarily gains read access to a database full of
* SturdyRefs: it would be unfortunate if it were then necessary to revoke every single reference
* in the database to prevent the attacker from using them.
*
* In general, an "owner" is a course-grained identity. Because capability-based security is still
* the primary mechanism of security, it is not necessary nor desirable to have a separate "owner"
* identity for every single process or object; that is exactly what capabilities are supposed to
* avoid! Instead, it makes sense for an "owner" to literally identify the owner of the machines
* where the capability is stored. If untrusted third parties are able to run arbitrary code on
* said machines, then the sandbox for that code should be designed using Distributed Confinement
* such that the third-party code never sees the bits of the SturdyRefs and cannot directly
* exercise the owner's power to restore refs. See:
*
*     http://www.erights.org/elib/capability/dist-confine.html
*
* Resist the urge to represent an Owner as a simple public key. The whole point of sealing is to
* defend against leaked-storage attacks. Such attacks can easily result in the owner's private
* key being stolen as well. A better solution is for `Owner` to contain a simple globally unique
* identifier for the owner, and for everyone to separately maintain a mapping of owner IDs to
* public keys. If an owner's private key is compromised, then humans will need to communicate
* and agree on a replacement public key, then update the mapping.
*
* As a concrete example, an `Owner` could simply contain a domain name, and restoring a SturdyRef
* would require signing a request using the domain's private key. Authenticating this key could
* be accomplished through certificate authorities or web-of-trust techniques.
*
*/
declare class Persistent extends Interface {
  static readonly SaveParams: typeof Persistent_SaveParams;
  static readonly SaveResults: typeof Persistent_SaveResults;
  static readonly Client: typeof Persistent$Client;
  static readonly Server: typeof Persistent$Server;
  static readonly _capnp: {
    displayName: string;
    id: string;
    size: any;
  };
  toString(): string;
}
//#endregion
export { Persistent, Persistent$Client, Persistent$Server, Persistent$Server$Target, Persistent_SaveParams, Persistent_SaveResults, Persistent_SaveResults$Promise, _capnpFileId };
//# sourceMappingURL=persistent.d.mts.map