@cubist-labs/cubesigner-sdk 0.4.209 → 0.4.217

package/src/policy.ts

@@ -1,9 +1,10 @@
 import type {
   ApiClient,
+  C2FResponse,
   CubeSignerResponse,
   EditPolicy,
   Empty,
-  InvokePolicyResponse,
+  InvokeC2FResponse,
   JsonValue,
   KeyPolicy,
   KeyPolicyRule,
@@ -14,8 +15,10 @@ import type {
   RolePolicy,
   RolePolicyRule,
   UpdatePolicyRequest,
-  WasmPolicyResponse,
   WasmRule,
+  Acl,
+  AceAttribute,
+  PolicyAction,
 } from ".";
 
 import { loadSubtleCrypto } from ".";
@@ -25,43 +28,77 @@ import { loadSubtleCrypto } from ".";
  */
 export type PolicyRule = KeyPolicyRule | RolePolicyRule | WasmRule;
 
+/**
+ * A helper type for {@link PolicyInfo} with a more detailed `acl` type.
+ */
+type NamedPolicyInfo = PolicyInfo & {
+  acl?: Acl<PolicyAction, PolicyCtx>;
+};
+
 /**
  * The policy info for a named key policy.
  */
-export type KeyPolicyInfo = PolicyInfo & {
+export type KeyPolicyInfo = NamedPolicyInfo & {
   policy_type: "Key";
 };
 
 /**
  * The policy info for a named role policy.
  */
-export type RolePolicyInfo = PolicyInfo & {
+export type RolePolicyInfo = NamedPolicyInfo & {
   policy_type: "Role";
 };
 
 /**
  * The policy info for a named wasm policy.
  */
-export type WasmPolicyInfo = PolicyInfo & {
+export type WasmPolicyInfo = NamedPolicyInfo & {
   policy_type: "Wasm";
 };
 
+/**
+ * The policy info for a Confidential Cloud Function.
+ */
+export type C2FInfo = WasmPolicyInfo;
+
 /**
  * A helper type for valid named policy version strings.
  */
 export type Version = `v${number}` | `latest`;
 
+/** A policy access control entry. */
+export type PolicyAcl = Acl<PolicyAction, PolicyCtx>;
+
+/** Additional contexts when using policies. */
+export type PolicyCtx = {
+  /**
+   * The resources (keys, roles, and key-in-roles) that the access control entry
+   * applies to.
+   */
+  resources: AceAttribute<PolicyResource>;
+};
+
+/** A resource a policy is invoked with or attached to. */
+export type PolicyResource =
+  /** A key or role id. */
+  | string
+  /** Keys attached to roles. */
+  | { key_ids: "*" | string[]; role_ids: "*" | string[] };
+
 /**
- * Upload the given Wasm policy object.
+ * Upload the given Wasm Confidential Cloud Function.
  *
  * @param apiClient The API client to use.
- * @param policy The Wasm policy object.
- * @returns The Wasm policy object hash to use for creating/updating policies.
+ * @param policy The Wasm function.
+ * @returns The Wasm function object hash to use for creating/updating C2F policies.
  * @throws if uploading the policy fails.
  * @internal
  */
-export async function uploadWasmPolicy(apiClient: ApiClient, policy: Uint8Array): Promise<string> {
-  // get the SHA-256 hash of the policy to get the upload url.
+export async function uploadWasmFunction(
+  apiClient: ApiClient,
+  policy: Uint8Array,
+): Promise<string> {
+  // get the SHA-256 hash of the function to get the upload url.
   const subtle = await loadSubtleCrypto();
   const hashBytes = await subtle.digest("SHA-256", policy);
   const hash = "0x" + Buffer.from(hashBytes).toString("hex");
@@ -69,25 +106,36 @@ export async function uploadWasmPolicy(apiClient: ApiClient, policy: Uint8Array)
   // get the upload URL
   const { signed_url } = await apiClient.wasmPolicyUpload({ hash });
 
-  // upload the policy object
+  // upload the wasm object
   const resp = await fetch(signed_url, {
     method: "PUT",
     body: policy,
   });
 
   if (!resp.ok) {
-    throw new Error(`Failed to upload policy with status: ${resp.status}: ${resp.statusText}`);
+    throw new Error(`Failed to upload function with status: ${resp.status}: ${resp.statusText}`);
   }
 
   return hash;
 }
 
+/**
+ * Upload the given Wasm policy.
+ *
+ * @param apiClient The API client to use.
+ * @param policy The Wasm function.
+ * @returns The Wasm function object hash to use for creating/updating C2F policies.
+ * @throws if uploading the policy fails.
+ * @internal
+ */
+export const uploadWasmPolicy = uploadWasmFunction;
+
 /**
  * Abstract class for shared methods between key, role and Wasm policies.
  */
 export abstract class NamedPolicy {
   protected readonly apiClient: ApiClient;
-  protected data: PolicyInfo;
+  protected data: NamedPolicyInfo;
 
   /**
    * Helper method for creating a named policy from a policy info.
@@ -103,7 +151,7 @@ export abstract class NamedPolicy {
       case "Role":
         return new NamedRolePolicy(apiClient, info as RolePolicyInfo);
       case "Wasm":
-        return new NamedWasmPolicy(apiClient, info as WasmPolicyInfo);
+        return new C2FFunction(apiClient, info as C2FInfo);
     }
   }
 
@@ -129,7 +177,7 @@ export abstract class NamedPolicy {
     if (version == `v${this.data.version}`) {
       versionInfo = this.data;
     } else {
-      versionInfo = await this.apiClient.policyGet(this.id, version);
+      versionInfo = (await this.apiClient.policyGet(this.id, version)) as NamedPolicyInfo;
     }
 
     return new NamedPolicyRules(this.apiClient, versionInfo);
@@ -199,9 +247,9 @@ export abstract class NamedPolicy {
   }
 
   /**
-   * Sets a new metadata value for the contact (overwriting the existing value).
+   * Sets a new metadata value for the named policy (overwriting the existing value).
    *
-   * @param metadata The new metadata for the contact.
+   * @param metadata The new metadata for the named policy.
    * @param mfaReceipt Optional MFA receipt(s).
    * @throws if MFA is required and no receipts are provided
    */
@@ -210,7 +258,7 @@ export abstract class NamedPolicy {
   }
 
   /**
-   * Fetch and return the edit policy for the contact.
+   * Fetch and return the edit policy for the named policy.
    *
    * @returns The edit policy for this named policy.
    */
@@ -230,6 +278,27 @@ export abstract class NamedPolicy {
     await this.update({ edit_policy: editPolicy }, mfaReceipt);
   }
 
+  /**
+   * Fetch and return the access control entries for the named policy.
+   *
+   * @returns The access control entries for this named policy.
+   */
+  async acl(): Promise<PolicyAcl | undefined> {
+    const data = await this.fetch();
+    return data.acl;
+  }
+
+  /**
+   * Sets new access control entries for the named policy (overwriting the existing entries).
+   *
+   * @param acl The access control entries to set.
+   * @param mfaReceipt Optional MFA receipt(s).
+   * @throws if MFA is required and no receipts are provided
+   */
+  async setAcl(acl: PolicyAcl, mfaReceipt?: MfaReceipts) {
+    await this.update({ acl }, mfaReceipt);
+  }
+
   /**
    * @returns a list of all keys, roles, and key-in-roles that all versions of this policy
    * are attached to.
@@ -282,7 +351,7 @@ export abstract class NamedPolicy {
    * @param data The JSON response from the API server.
    * @internal
    */
-  protected constructor(apiClient: ApiClient, data: PolicyInfo) {
+  protected constructor(apiClient: ApiClient, data: NamedPolicyInfo) {
     this.apiClient = apiClient;
     this.data = data;
   }
@@ -299,9 +368,9 @@ export abstract class NamedPolicy {
   protected async update(
     request: UpdatePolicyRequest,
     mfaReceipt?: MfaReceipts,
-  ): Promise<PolicyInfo> {
+  ): Promise<NamedPolicyInfo> {
     const resp = await this.apiClient.policyUpdate(this.id, request, mfaReceipt);
-    this.data = resp.data();
+    this.data = resp.data() as NamedPolicyInfo;
     return this.data;
   }
 
@@ -312,8 +381,8 @@ export abstract class NamedPolicy {
    * @returns The policy information.
    * @internal
    */
-  protected async fetch(version: Version = "latest"): Promise<PolicyInfo> {
-    this.data = await this.apiClient.policyGet(this.id, version);
+  protected async fetch(version: Version = "latest"): Promise<NamedPolicyInfo> {
+    this.data = (await this.apiClient.policyGet(this.id, version)) as NamedPolicyInfo;
     return this.data;
   }
 }
@@ -387,44 +456,47 @@ export class NamedRolePolicy extends NamedPolicy {
 }
 
 /**
- * A representation of a Wasm policy.
+ * A representation of a Confidential Cloud Function (C2F).
+ *
+ * This class extends NamedPolicy because C2F functions can be attached
+ * to keys and roles like a named policy.
  */
-export class NamedWasmPolicy extends NamedPolicy {
-  override data: WasmPolicyInfo;
+export class C2FFunction extends NamedPolicy {
+  override data: C2FInfo;
 
   /**
-   * Update the policy with the new Wasm policy.
+   * Update this C2F function with a new Wasm function.
    *
-   * @param policy The new Wasm policy object.
+   * @param policy The new Wasm function.
    * @param mfaReceipt Optional MFA receipt(s).
-   * @throws if uploading the policy object fails.
+   * @throws if uploading the function fails.
    * @throws if MFA is required and no receipts are provided.
    */
-  async setWasmPolicy(policy: Uint8Array, mfaReceipt?: MfaReceipts) {
+  async setWasmFunction(policy: Uint8Array, mfaReceipt?: MfaReceipts) {
     // upload the policy object
-    const hash = await uploadWasmPolicy(this.apiClient, policy);
+    const hash = await uploadWasmFunction(this.apiClient, policy);
 
     // update this policy with the new policy verison.
     const body: UpdatePolicyRequest = { rules: [{ hash }] };
-    this.data = (await this.update(body, mfaReceipt)) as WasmPolicyInfo;
+    this.data = (await this.update(body, mfaReceipt)) as C2FInfo;
   }
 
   /**
-   * Invoke this wasm policy.
+   * Invoke this Confidential Cloud Function.
    *
-   * @param keyId The optional key id that the policy will be invoked with.
-   * @param version The version of the policy to invoke. Defaults to "latest".
-   * @param request The optional sign request body that will be sent to the policy.
-   * @param roleId The optional role id that the policy will be invoked by.
+   * @param keyId The optional key id that the function will be invoked with.
+   * @param version The version of the function to invoke. Defaults to "latest".
+   * @param request The optional sign request body that will be sent to the function.
+   * @param roleId The optional role id that the function will be invoked by.
    * If `undefined`, the policy will be invoked by the user session.
-   * @returns The result of invoking the policy.
+   * @returns The result of invoking the function.
    */
   async invoke(
     keyId?: string,
     version: Version = "latest",
     request?: JsonValue,
     roleId?: string,
-  ): Promise<PolicyInvocation> {
+  ): Promise<C2FInvocation> {
     // TODO Ideally, `version` should be the first parameter. But for backwards
     // compatibility, we keep `keyId` as the first parameter for now.
     const resp = await this.apiClient.policyInvoke(this.id, version, {
@@ -435,6 +507,17 @@ export class NamedWasmPolicy extends NamedPolicy {
     return new PolicyInvocation(resp);
   }
 
+  // Backwards compability with Named Wasm Policy names
+  /**
+   * Update the policy with the new Wasm policy.
+   *
+   * @param policy The new Wasm policy object.
+   * @param mfaReceipt Optional MFA receipt(s).
+   * @throws if uploading the policy object fails.
+   * @throws if MFA is required and no receipts are provided.
+   */
+  setWasmPolicy = this.setWasmFunction;
+
   // --------------------------------------------------------------------------
   // -- INTERNAL --------------------------------------------------------------
   // --------------------------------------------------------------------------
@@ -446,7 +529,7 @@ export class NamedWasmPolicy extends NamedPolicy {
    * @param data The JSON response from the API server.
    * @internal
    */
-  constructor(apiClient: ApiClient, data: WasmPolicyInfo) {
+  constructor(apiClient: ApiClient, data: C2FInfo) {
     super(apiClient, data);
     this.data = data;
   }
@@ -458,7 +541,7 @@ export class NamedWasmPolicy extends NamedPolicy {
 export class NamedPolicyRules {
   /** The CubeSigner instance that this policy is associated with */
   readonly #apiClient: ApiClient;
-  #data: PolicyInfo;
+  #data: NamedPolicyInfo;
 
   /**
    * @returns The ID of the policy.
@@ -505,7 +588,7 @@ export class NamedPolicyRules {
    * @param data The JSON response from the API server.
    * @internal
    */
-  constructor(apiClient: ApiClient, data: PolicyInfo) {
+  constructor(apiClient: ApiClient, data: NamedPolicyInfo) {
     this.#apiClient = apiClient;
     this.#data = data;
   }
@@ -516,20 +599,20 @@ export class NamedPolicyRules {
    * @returns The policy information.
    * @internal
    */
-  private async fetch(): Promise<PolicyInfo> {
-    this.#data = await this.#apiClient.policyGet(this.id, this.version);
+  private async fetch(): Promise<NamedPolicyInfo> {
+    this.#data = (await this.#apiClient.policyGet(this.id, this.version)) as NamedPolicyInfo;
     return this.#data;
   }
 }
 
 /**
- * The result of invoking a named wasm policy.
+ * The result of invoking a Confidential Cloud Function.
  */
-export class PolicyInvocation {
-  readonly #data: InvokePolicyResponse;
+export class C2FInvocation {
+  readonly #data: InvokeC2FResponse;
 
   /** @returns The policy response itself. */
-  get response(): WasmPolicyResponse {
+  get response(): C2FResponse {
     return this.#data.response;
   }
 
@@ -563,7 +646,19 @@ export class PolicyInvocation {
    * @param data The JSON response from the API server.
    * @internal
    */
-  constructor(data: InvokePolicyResponse) {
+  constructor(data: InvokeC2FResponse) {
     this.#data = data;
   }
 }
+
+// Backwards compability with Named Wasm Policy names
+
+/** A representation of a Wasm policy. */
+export type NamedWasmPolicy = C2FFunction;
+/** A representation of a Wasm policy. */
+export const NamedWasmPolicy = C2FFunction;
+
+/** The result of invoking a named WASM policy. */
+export type PolicyInvocation = C2FInvocation;
+/** The result of invoking a named WASM policy. */
+export const PolicyInvocation = C2FInvocation;