### Install Meadowcap

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Import the Meadowcap class from the JSR package.

```typescript
// Import from JSR (Deno/Node.js)
import { Meadowcap } from "@earthstar/meadowcap";
```

--------------------------------

### Configure Meadowcap Instance

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Initialize the Meadowcap manager with custom cryptographic schemes, path constraints, and namespace logic.

```typescript
import { Meadowcap } from "@earthstar/meadowcap";
import type { KeypairScheme } from "@earthstar/willow-utils";

// Define your cryptographic scheme (example using ECDSA)
const ecdsaScheme: KeypairScheme<ArrayBuffer, CryptoKey, ArrayBuffer> = {
  encodings: {
    publicKey: {
      encode: (key) => new Uint8Array(key),
      decode: (key) => key.buffer,
      encodedLength: () => 65,
      decodeStream: async (bytes) => { /* streaming decode */ },
    },
    signature: {
      encode: (sig) => new Uint8Array(sig),
      decode: (enc) => enc.buffer,
      encodedLength: () => 64,
      decodeStream: async (bytes) => { /* streaming decode */ },
    },
  },
  signatures: {
    sign: async (publicKey, secretKey, message) => {
      return crypto.subtle.sign(
        { name: "ECDSA", hash: { name: "SHA-256" } },
        secretKey,
        message
      );
    },
    verify: async (publicKey, signature, message) => {
      const key = await crypto.subtle.importKey(
        "raw", publicKey,
        { name: "ECDSA", namedCurve: "P-256" },
        true, ["verify"]
      );
      return crypto.subtle.verify(
        { name: "ECDSA", hash: { name: "SHA-256" } },
        key, signature, message
      );
    },
  },
};

// Create a Meadowcap instance
const mc = new Meadowcap({
  namespaceKeypairScheme: ecdsaScheme,
  userScheme: {
    ...ecdsaScheme,
    order: (a, b) => {
      // Total ordering function for public keys
      const ua = new Uint8Array(a);
      const ub = new Uint8Array(b);
      for (let i = 0; i < ua.length; i++) {
        if (ua[i] < ub[i]) return -1;
        if (ua[i] > ub[i]) return 1;
      }
      return 0;
    },
  },
  pathScheme: {
    maxComponentCount: 16,
    maxComponentLength: 64,
    maxPathLength: 1024,
  },
  payloadScheme: {
    encode: (buffer) => new Uint8Array(buffer),
    decode: (enc) => enc.buffer,
    encodedLength: () => 32,
    decodeStream: async (bytes) => { /* streaming decode */ },
  },
  // Determine if namespace is communal based on public key
  isCommunal: (pubkey) => {
    const ui8 = new Uint8Array(pubkey);
    return (ui8[ui8.length - 1] & 0x1) === 0x1;
  },
});
```

--------------------------------

### createCapOwned - Create Owned Namespace Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Creates a capability for an owned namespace where authority is derived from the namespace keypair. Requires the namespace secret key to sign the initial authorization.

```APIDOC
## createCapOwned - Create Owned Namespace Capability

### Description
Creates a capability for an owned namespace where authority is derived from the namespace keypair. Requires the namespace secret key to sign the initial authorization.

### Method
POST (inferred)

### Endpoint
/api/capabilities/owned (inferred)

### Parameters
#### Request Body
- **accessMode** (string) - Required - The access mode for the capability (e.g., "write", "read").
- **namespace** (PublicKey) - Required - The public key of the namespace.
- **namespaceSecret** (PrivateKey) - Required - The secret key of the namespace for signing.
- **user** (PublicKey) - Required - The public key of the user the capability is for.

### Request Example
```json
{
  "accessMode": "write",
  "namespace": "<namespace_public_key_bytes>",
  "namespaceSecret": "<namespace_private_key_bytes>",
  "user": "<user_public_key_bytes>"
}
```

### Response
#### Success Response (200)
- **accessMode** (string) - The access mode of the created capability.
- **namespaceKey** (PublicKey) - The namespace public key.
- **userKey** (PublicKey) - The user public key.
- **initialAuthorisation** (Signature) - The initial authorization signature.
- **delegations** (array) - An empty array for newly created owned capabilities.

#### Response Example
```json
{
  "accessMode": "write",
  "namespaceKey": "<namespace_public_key_bytes>",
  "userKey": "<user_public_key_bytes>",
  "initialAuthorisation": "<signature_bytes>",
  "delegations": []
}
```
```

--------------------------------

### Import Meadowcap Semantic Helper Functions

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Import standalone functions to extract information from capabilities without needing a Meadowcap instance. These functions help in understanding the scope and ownership of a capability.

```typescript
import {
  getGrantedNamespace,
  getReceiver,
  getGrantedAreaCommunal,
  getGrantedAreaOwned,
  getReceiverSubspaceCap,
} from "@earthstar/meadowcap";
```

--------------------------------

### createCapCommunal - Create Communal Namespace Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Creates a capability for a communal namespace where authority is derived from subspace ownership. This grants access to the user's entire subspace.

```APIDOC
## createCapCommunal

### Description
Creates a capability for a communal namespace where authority is derived from subspace ownership. The initial capability grants access to the user's entire subspace with no time or path restrictions.

### Parameters
#### Request Body
- **accessMode** (string) - Required - The mode of access, either "read" or "write".
- **namespace** (ArrayBuffer) - Required - The public key of the namespace.
- **user** (ArrayBuffer) - Required - The public key of the user.

### Request Example
{
  "accessMode": "read",
  "namespace": "<namespacePublicKey>",
  "user": "<userPublicKey>"
}

### Response
#### Success Response (200)
- **accessMode** (string) - The granted access mode.
- **namespaceKey** (ArrayBuffer) - The namespace public key.
- **userKey** (ArrayBuffer) - The user public key.
- **delegations** (Array) - List of capability delegations.

#### Response Example
{
  "accessMode": "read",
  "namespaceKey": "<namespacePublicKey>",
  "userKey": "<userPublicKey>",
  "delegations": []
}
```

--------------------------------

### Import Meadowcap Error Handling Utilities

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Import custom error classes and type guard utilities for robust error handling in your Meadowcap interactions. This includes `MeadowcapError`, `InvalidCapError`, `isErr`, and `notErr`.

```typescript
import { MeadowcapError, InvalidCapError, isErr, notErr } from "@earthstar/meadowcap";
```

--------------------------------

### Handle Meadowcap Errors with Try-Catch

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Use a try-catch block to gracefully handle potential errors during capability creation or other Meadowcap operations. Differentiate between general `MeadowcapError` and specific `InvalidCapError` for targeted error management.

```typescript
try {
  // Attempting to create communal cap for owned namespace throws
  const cap = mc.createCapCommunal({
    accessMode: "read",
    namespace: ownedNamespaceKey, // Not communal!
    user: userPublicKey,
  });
} catch (err) {
  if (err instanceof MeadowcapError) {
    console.log("Meadowcap error:", err.message);
  }
  if (err instanceof InvalidCapError) {
    console.log("Invalid capability:", err.message);
  }
}
```

--------------------------------

### Create Owned Namespace Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Generates a capability for an owned namespace. Requires the namespace secret key for signing. Ensure the namespace is not communal.

```typescript
// Generate an owned namespace keypair (ensure isCommunal returns false)
const namespaceKeypair = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true, ["sign", "verify"]
);
const namespacePublicKey = await crypto.subtle.exportKey("raw", namespaceKeypair.publicKey);

const userKeypair = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true, ["sign", "verify"]
);
const userPublicKey = await crypto.subtle.exportKey("raw", userKeypair.publicKey);

// Create an owned capability (async - requires signing)
const ownedCap = await mc.createCapOwned({
  accessMode: "write",
  namespace: namespacePublicKey,
  namespaceSecret: namespaceKeypair.privateKey,
  user: userPublicKey,
});
// Result: { accessMode: "write", namespaceKey, userKey, initialAuthorisation, delegations: [] }

// Verify the capability is valid
const isValid = await mc.isValidCap(ownedCap);
console.log("Capability valid:", isValid); // true
```

--------------------------------

### Create Communal Namespace Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Generate read or write capabilities for a communal namespace using subspace ownership keys.

```typescript
// Generate keypairs
const namespaceKeypair = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true, ["sign", "verify"]
);
const namespacePublicKey = await crypto.subtle.exportKey("raw", namespaceKeypair.publicKey);

const userKeypair = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true, ["sign", "verify"]
);
const userPublicKey = await crypto.subtle.exportKey("raw", userKeypair.publicKey);

// Create a read capability for communal namespace
const readCap = mc.createCapCommunal({
  accessMode: "read",
  namespace: namespacePublicKey,
  user: userPublicKey,
});
// Result: { accessMode: "read", namespaceKey, userKey, delegations: [] }

// Create a write capability for communal namespace
const writeCap = mc.createCapCommunal({
  accessMode: "write",
  namespace: namespacePublicKey,
  user: userPublicKey,
});
// Result: { accessMode: "write", namespaceKey, userKey, delegations: [] }
```

--------------------------------

### Import Meadowcap Capability Types

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Import various capability types for use in your TypeScript project. These include access modes, communal and owned capabilities, union types, subspace capabilities, and delegation tuples.

```typescript
import type {
  // Access mode
  AccessMode, // "read" | "write"

  // Communal capabilities
  CommunalCapability,
  CommunalReadCapability,
  CommunalWriteCapability,

  // Owned capabilities
  OwnedCapability,
  OwnedReadCapability,
  OwnedWriteCapability,

  // Union types
  McCapability, // CommunalCapability | OwnedCapability
  ReadCapability,
  WriteCapability,

  // Subspace capabilities
  McSubspaceCapability,

  // Delegation tuple
  Delegation, // [Area, UserPublicKey, UserSignature]
} from "@earthstar/meadowcap";
```

--------------------------------

### Extract Capability Information using Helper Functions

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Utilize helper functions to retrieve the namespace, owner, granted area, or subspace receiver associated with a capability. Ensure you use the correct function based on the capability type (communal, owned, or subspace).

```typescript
// Get the namespace a capability grants access to
const namespace = getGrantedNamespace(cap);

// Get the current receiver (owner) of a capability
const receiver = getReceiver(cap);

// Get granted area for communal capability
const communalArea = getGrantedAreaCommunal(communalCap);

// Get granted area for owned capability
const ownedArea = getGrantedAreaOwned(ownedCap);

// Get receiver of subspace capability
const subspaceReceiver = getReceiverSubspaceCap(subspaceCap);
```

--------------------------------

### delegateCapCommunal - Delegate Communal Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Delegates a communal capability to another user, optionally restricting it to a smaller area (time range, path prefix, subspace). The delegation must be signed with the current receiver's secret key.

```APIDOC
## delegateCapCommunal - Delegate Communal Capability

### Description
Delegates a communal capability to another user, optionally restricting it to a smaller area (time range, path prefix, subspace). The delegation must be signed with the current receiver's secret key.

### Method
POST (inferred)

### Endpoint
/api/capabilities/delegate/communal (inferred)

### Parameters
#### Request Body
- **cap** (Capability) - Required - The communal capability to delegate.
- **user** (PublicKey) - Required - The public key of the user to delegate to.
- **secret** (PrivateKey) - Required - The secret key of the current receiver to sign the delegation.
- **area** (object) - Optional - Restrictions for the delegation.
  - **pathPrefix** (array of Uint8Array) - Optional - Restricts to paths starting with these prefixes.
  - **timeRange** (object) - Optional - Restricts to a specific time range.
    - **start** (BigInt) - Required - The start of the time range.
    - **end** (BigInt) - Required - The end of the time range.
  - **includedSubspaceId** (PublicKey) - Optional - Restricts to a specific subspace.

### Request Example
```json
{
  "cap": {
    "accessMode": "write",
    "namespace": "<namespace_public_key_bytes>",
    "user": "<alice_public_key_bytes>"
  },
  "user": "<bob_public_key_bytes>",
  "secret": "<alice_private_key_bytes>",
  "area": {
    "pathPrefix": [ [1, 2] ],
    "timeRange": {
      "start": 1000,
      "end": 2000
    },
    "includedSubspaceId": "<alice_public_key_bytes>"
  }
}
```

### Response
#### Success Response (200)
- **delegatedCap** (Capability) - The newly created delegated capability.

#### Response Example
```json
{
  "delegatedCap": {
    "accessMode": "write",
    "namespace": "<namespace_public_key_bytes>",
    "user": "<bob_public_key_bytes>",
    "delegations": [
      {
        "signature": "<delegation_signature_bytes>",
        "area": {
          "pathPrefix": [ [1, 2] ],
          "timeRange": {
            "start": 1000,
            "end": 2000
          },
          "includedSubspaceId": "<alice_public_key_bytes>"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Verify Write Authorization with Meadowcap

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Use `isAuthorisedWrite` to check if a MeadowcapAuthorisationToken grants write access to a specific entry. Ensure the capability, entry, and signature are valid before proceeding.

```typescript
import { encodeEntry, type Entry } from "@earthstar/willow-utils";

// Create a write capability
const writeCap = mc.createCapCommunal({
  accessMode: "write",
  namespace: namespacePublicKey,
  user: userPublicKey,
});

// Create an entry to write
const payload = new TextEncoder().encode("Hello, Willow!");
const entry: Entry<ArrayBuffer, ArrayBuffer, ArrayBuffer> = {
  namespaceId: namespacePublicKey,
  subspaceId: userPublicKey,
  path: [new TextEncoder().encode("greeting")],
  payloadLength: BigInt(payload.byteLength),
  payloadDigest: await crypto.subtle.digest("SHA-256", payload),
  timestamp: BigInt(Date.now() * 1000), // Microseconds
};

// Encode and sign the entry
const encodedEntry = encodeEntry({
  encodeNamespace: (key) => new Uint8Array(key),
  encodeSubspace: (key) => new Uint8Array(key),
  pathScheme: { maxComponentCount: 16, maxComponentLength: 64, maxPathLength: 1024 },
  encodePayload: (buffer) => new Uint8Array(buffer),
}, entry);

const entrySignature = await ecdsaScheme.signatures.sign(
  userPublicKey,
  userPrivateKey,
  encodedEntry
);

// Create authorization token
const authToken = {
  capability: writeCap,
  signature: entrySignature,
};

// Verify write is authorized
const isAuthorized = await mc.isAuthorisedWrite(entry, authToken);
console.log("Write authorized:", isAuthorized); // true

// Attempt unauthorized write (different subspace)
const unauthorizedEntry = { ...entry, subspaceId: otherUserPublicKey };
const isUnauthorized = await mc.isAuthorisedWrite(unauthorizedEntry, authToken);
console.log("Unauthorized write:", isUnauthorized); // false
```

--------------------------------

### Validate Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Verifies the cryptographic validity of a capability's entire delegation chain. Returns true if all signatures are valid, false otherwise.

```typescript
// Create and validate a capability
const cap = mc.createCapCommunal({
  accessMode: "read",
  namespace: namespacePublicKey,
  user: userPublicKey,
});

const isValid = await mc.isValidCap(cap);
console.log("Root capability valid:", isValid); // true

// Delegate with correct secret
const validDelegation = await mc.delegateCapCommunal({
  cap,
  user: delegeePublicKey,
  secret: userPrivateKey, // Correct secret
  area: mc.getCapGrantedArea(cap),
});
console.log("Valid delegation:", await mc.isValidCap(validDelegation)); // true

// Delegate with wrong secret (produces invalid capability)
const invalidDelegation = await mc.delegateCapCommunal({
  cap,
  user: delegeePublicKey,
  secret: wrongPrivateKey, // Wrong secret!
  area: mc.getCapGrantedArea(cap),
});
console.log("Invalid delegation:", await mc.isValidCap(invalidDelegation)); // false
```

--------------------------------

### Manage Subspace Capabilities for Read Access

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Use `needsSubspaceCap` to determine if a capability requires a subspace capability, typically for read access to arbitrary subspaces with path restrictions. Create and validate subspace capabilities using `createSubspaceCap` and `isValidSubspaceCap`.

```typescript
// Check if an owned capability needs a subspace capability
const readCap = await mc.createCapOwned({
  accessMode: "read",
  namespace: namespacePublicKey,
  namespaceSecret: namespacePrivateKey,
  user: userPublicKey,
});

// Root capability doesn't need subspace cap
console.log("Needs subspace cap:", mc.needsSubspaceCap(readCap)); // false

// Delegate with path restriction but ANY_SUBSPACE
const restrictedCap = await mc.delegateCapOwned({
  cap: readCap,
  user: delegeePublicKey,
  secret: userPrivateKey,
  area: {
    includedSubspaceId: ANY_SUBSPACE,
    pathPrefix: [new TextEncoder().encode("data")], // Non-empty path!
    timeRange: { start: 0n, end: OPEN_END },
  },
});

// Now it needs a subspace capability
console.log("Needs subspace cap:", mc.needsSubspaceCap(restrictedCap)); // true

// Create a subspace capability
const subspaceCap = await mc.createSubspaceCap(
  namespacePublicKey,
  namespacePrivateKey,
  userPublicKey
);

// Validate subspace capability
console.log("Subspace cap valid:", await mc.isValidSubspaceCap(subspaceCap)); // true

// Delegate subspace capability
const delegatedSubspaceCap = await mc.delegateSubspaceCap(
  subspaceCap,
  delegeePublicKey,
  userPrivateKey // Current receiver's secret
);

console.log("Delegated valid:", await mc.isValidSubspaceCap(delegatedSubspaceCap)); // true
```

--------------------------------

### Encode and Decode Meadowcap Capabilities

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Encode capabilities to `Uint8Array` for storage or transmission using `encodeCap` and `encodeSubspaceCap`. Decode them back into capability objects using `decodeCap` and `decodeSubspaceCap`. Supports omitting the namespace during encoding for subspace capabilities when the namespace is already known.

```typescript
// Create a capability
const cap = await mc.createCapOwned({
  accessMode: "write",
  namespace: namespacePublicKey,
  namespaceSecret: namespacePrivateKey,
  user: userPublicKey,
});

// Encode to bytes
const encoded: Uint8Array = mc.encodeCap(cap);
console.log("Encoded length:", encoded.byteLength);

// Decode from bytes
const decoded = mc.decodeCap(encoded);
console.log("Decoded access mode:", decoded.accessMode); // "write"
console.log("Valid after decode:", await mc.isValidCap(decoded)); // true

// Encode subspace capability (optionally omit namespace if known)
const subspaceCap = await mc.createSubspaceCap(
  namespacePublicKey,
  namespacePrivateKey,
  userPublicKey
);

const encodedSubspace = mc.encodeSubspaceCap(subspaceCap);
const encodedOmitNs = mc.encodeSubspaceCap(subspaceCap, true); // Omit namespace

// Decode with known namespace
const decodedSubspace = mc.decodeSubspaceCap(encodedOmitNs, namespacePublicKey);

// Streaming decode for network protocols (using GrowingBytes)
// const streamDecoded = await mc.decodeStreamingCap(growingBytesStream);
```

--------------------------------

### Type Guard for Capability Type Checking

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Use this type guard to differentiate between communal and owned capabilities at runtime. This allows you to safely access properties specific to each capability type.

```typescript
// Type guard for checking capability type
if (mc.isCommunal(someCap)) {
  // someCap is CommunalCapability
  const area = getGrantedAreaCommunal(someCap);
} else {
  // someCap is OwnedCapability
  const area = getGrantedAreaOwned(someCap);
}
```

--------------------------------

### Delegate Communal Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Delegates a communal capability to another user, with optional restrictions on path, time, or subspace. The delegation must be signed by the current receiver's secret key.

```typescript
import { OPEN_END } from "@earthstar/willow-utils";

// Original user's capability
const originalCap = mc.createCapCommunal({
  accessMode: "write",
  namespace: namespacePublicKey,
  user: alicePublicKey,
});

// Alice delegates to Bob with restrictions
const delegatedCap = await mc.delegateCapCommunal({
  cap: originalCap,
  user: bobPublicKey,
  secret: alicePrivateKey, // Current receiver's secret
  area: {
    pathPrefix: [new Uint8Array([0x01, 0x02])], // Restrict to paths starting with [1, 2]
    timeRange: {
      start: BigInt(1000),
      end: BigInt(2000), // Restrict to time range 1000-2000
    },
    includedSubspaceId: alicePublicKey, // Must stay within original subspace
  },
});

// Bob can further delegate to Carol with even more restrictions
const furtherDelegated = await mc.delegateCapCommunal({
  cap: delegatedCap,
  user: carolPublicKey,
  secret: bobPrivateKey,
  area: {
    pathPrefix: [new Uint8Array([0x01, 0x02]), new Uint8Array([0x03])],
    timeRange: {
      start: BigInt(1200),
      end: BigInt(1800), // Must be subset of previous range
    },
    includedSubspaceId: alicePublicKey,
  },
});

// Verify delegation chain
console.log("Valid:", await mc.isValidCap(furtherDelegated)); // true
console.log("Receiver:", mc.getCapReceiver(furtherDelegated)); // Carol's public key
```

--------------------------------

### isValidCap - Validate Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Validates that a capability's entire delegation chain has valid signatures. Returns a boolean indicating whether the capability is cryptographically valid.

```APIDOC
## isValidCap - Validate Capability

### Description
Validates that a capability's entire delegation chain has valid signatures. Returns a boolean indicating whether the capability is cryptographically valid.

### Method
POST (inferred)

### Endpoint
/api/capabilities/validate (inferred)

### Parameters
#### Request Body
- **cap** (Capability) - Required - The capability to validate.

### Request Example
```json
{
  "cap": {
    "accessMode": "read",
    "namespace": "<namespace_public_key_bytes>",
    "user": "<user_public_key_bytes>"
  }
}
```

### Response
#### Success Response (200)
- **isValid** (boolean) - True if the capability is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

--------------------------------

### delegateCapOwned - Delegate Owned Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Delegates an owned capability to another user with optional area restrictions. Works similarly to communal delegation but for owned namespaces.

```APIDOC
## delegateCapOwned - Delegate Owned Capability

### Description
Delegates an owned capability to another user with optional area restrictions. Works similarly to communal delegation but for owned namespaces.

### Method
POST (inferred)

### Endpoint
/api/capabilities/delegate/owned (inferred)

### Parameters
#### Request Body
- **cap** (Capability) - Required - The owned capability to delegate.
- **user** (PublicKey) - Required - The public key of the user to delegate to.
- **secret** (PrivateKey) - Required - The secret key of the current receiver to sign the delegation.
- **area** (object) - Optional - Restrictions for the delegation.
  - **pathPrefix** (array of Uint8Array) - Optional - Restricts to paths starting with these prefixes.
  - **timeRange** (object) - Optional - Restricts to a specific time range.
    - **start** (BigInt) - Required - The start of the time range.
    - **end** (BigInt) - Required - The end of the time range.
  - **includedSubspaceId** (PublicKey or 'ANY_SUBSPACE') - Optional - Restricts to a specific subspace or any subspace.

### Request Example
```json
{
  "cap": {
    "accessMode": "read",
    "namespace": "<namespace_public_key_bytes>",
    "user": "<admin_public_key_bytes>",
    "namespaceSecret": "<namespace_private_key_bytes>"
  },
  "user": "<user_public_key_bytes>",
  "secret": "<admin_private_key_bytes>",
  "area": {
    "pathPrefix": [ [112, 97, 116, 104] ], // "public"
    "timeRange": {
      "start": 0,
      "end": null // OPEN_END
    },
    "includedSubspaceId": "ANY_SUBSPACE"
  }
}
```

### Response
#### Success Response (200)
- **delegatedCap** (Capability) - The newly created delegated capability.

#### Response Example
```json
{
  "delegatedCap": {
    "accessMode": "read",
    "namespace": "<namespace_public_key_bytes>",
    "user": "<user_public_key_bytes>",
    "delegations": [
      {
        "signature": "<delegation_signature_bytes>",
        "area": {
          "pathPrefix": [ [112, 97, 116, 104] ],
          "timeRange": {
            "start": 0,
            "end": null
          },
          "includedSubspaceId": "ANY_SUBSPACE"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Delegate Owned Capability

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Delegates an owned capability to another user, similar to communal delegation but for owned namespaces. Optional area restrictions can be applied.

```typescript
import { ANY_SUBSPACE } from "@earthstar/willow-utils";

// Create root owned capability
const rootCap = await mc.createCapOwned({
  accessMode: "read",
  namespace: namespacePublicKey,
  namespaceSecret: namespacePrivateKey,
  user: adminPublicKey,
});

// Admin delegates read access to a user for a specific area
const userCap = await mc.delegateCapOwned({
  cap: rootCap,
  user: userPublicKey,
  secret: adminPrivateKey,
  area: {
    pathPrefix: [new TextEncoder().encode("public")],
    timeRange: {
      start: BigInt(0),
      end: OPEN_END, // No end time restriction
    },
    includedSubspaceId: ANY_SUBSPACE, // Access all subspaces
  },
});

// Get granted area for the capability
const grantedArea = mc.getCapGrantedArea(userCap);
console.log("Path prefix:", grantedArea.pathPrefix);
console.log("Time range:", grantedArea.timeRange);
console.log("Subspace:", grantedArea.includedSubspaceId);
```

--------------------------------

### Use Type Guards for Operation Results

Source: https://context7.com/earthstar-project/meadowcap-js/llms.txt

Employ `isErr` and `notErr` type guards to check the outcome of operations that may return an error. This pattern simplifies conditional logic for handling success and failure states.

```typescript
// Type guard utilities
const result = someOperation();
if (isErr(result)) {
  console.log("Error occurred:", result.message);
} else if (notErr(result)) {
  console.log("Success:", result);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.