Skip to content

Latest commit

 

History

History
234 lines (212 loc) · 10.6 KB

Membrane.md

File metadata and controls

234 lines (212 loc) · 10.6 KB

Membrane Service

Membrane Service enables creation and management of capabilities.

Membrane Service can be constructed using the SDK as follows:

const CapabilitySdk = require("capability-sdk");
const membrane = new CapabilitySdk.Membrane();

Once an instance of the Membrane Service is created, you can use it to make calls to the Membrane Service.

membrane.create(createCapability, membrane, callback)

  • createCapability: Capability URI Capability to create membranes.
  • membrane: Object Membrane to create.
    • id: String Unique id to assign to the membrane.
  • callback: Function (error, response) => {}
    • error: Error Error, if any.
    • response: Object Response.
      • id: String Membrane id.
      • capabilities: Object Membrane capabilities.

Creates a new membrane. For example:

const createCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-CZ9zvxISLdPVIiEPdyO6P67yxBOrhTv3FiLji5Qcou3K6hCHchXy-AZMVpGkEA5-9avUoraS-8VjClQuxZnzFQ";
membrane.create(createCapability, {id: "my-first-membrane"}, (error, resp) =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
        else
        {
            console.log(resp); // successful response
        }
        /*
        response =
        {
            id: "my-first-membrane",
            capabilities:
            {
                export: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-E0dTSQY_Tq01tZtMAfQANR97S3jB8QXrDDv5dylF9-PM-MphtPmjWtTYmmiSHfuS3t0aXYVB0EM42JuLSsLLLA"
                revoke: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-1lCiUqEOUpQwe6XKWM8unsu4667NyS7kNYSIKCw6pEm2-zRnwDmdoJkarbN81_Bo_cwWnfuXR4_2LhvInpNCYw"
            }
        }
        */
    }
);

membrane.deleteSelf(deleteSelfCapability, callback)

  • deleteSelfCapability: Capability URI Capability to delete self.
  • callback: Function (error) => {}
    • error: Error Error, if any.

Deletes Membrane Service tenant (your account within Membrane Service). This will delete all membranes and capabilities, and revoke all tenant capabilities within Membrane Service.

Example:

const deleteSelfCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-OtWGOZF3FxlyVAh4chXhfy911Fcfa4N66hkMM-AF6cNEzc8AQYwhVYw0Bw13GDQOnGHVHF1_Ir90mr34zdH9Bg";
membrane.deleteSelf(deleteSelfCapability, error =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
    }
);

membrane.export(exportCapability, config, callback)

  • exportCapability: Capability URI Capability to export capability through membrane.
  • config: Object Configuration of the capability to export through membrane.
    • capability: Capability URI Mutually exclusive with uri. An already existing capability to re-export through this membrane. If this membrane is revoked, the original capability will not be revoked. Only the capability created during this re-export and any of its descendants will be revoked.
    • uri: String Mutually exclusive with capability. Fully qualified URI, for example https://example.com/path/to/something
    • allowQuery (uri option): Boolean (Default: false) Optionally allow requester's URI query string to be appended to the uri in membrane request.
    • headers (uri option): Object (Default: undefined) Optional headers to include with the membrane request to the URI. Hop-by-hop headers will be ignored.
    • hmac (uri option): Object (Default: undefined) Optional selector for which signature scheme to use to sign membrane request to URI.
      • aws4-hmac-sha256: Object Use AWS4-HMAC-SHA256 signature.
        • awsAccessKeyId: String AWS Access Key Id to sign requests with.
        • region: String AWS region capability is in.
        • service: String AWS service capability is in.
        • secretAccessKey: String AWS Secret Access Key to sign requests with.
      • cap1-hmac-sha512: Object Use CAP1-HMAC-SHA512 signature.
        • key: String Base64url encoded secret key bytes.
        • keyId: String Secret key id.
    • method (uri option): String (Default: undefined) Optional HTTP method to use in the membrane request to the URI. This overrides the method specified by the requester.
    • timeoutMs (uri option): Number (Default: undefined) Optional timeout in milliseconds to end idle connection between membrane and URI. Will be ignored if greater than membrane's configured internal timeout.
    • tls (uri option): Object (Default: undefined) TLS options.
      • ca: String (Default: undefined) Optionally, override default trusted Certificate Authorities (CAs). Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CA is explicitly specified using this option.
      • cert: String (Default: undefined) Optional certificate chain in PEM format.
      • key: String (Default: undefined) Optional private key in PEM format.
      • rejectUnauthorized: Boolean (Default: true) If not false, membrane request verifies responding server against the list of supplied Certificate Authorities.
  • callback: Function (error, response) => {}
    • error: Error Error, if any.
    • response: Object Response.
      • capability: Capability URI Created capability.

Exports a capability through the membrane per specified configuration. For example:

const exportCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-E0dTSQY_Tq01tZtMAfQANR97S3jB8QXrDDv5dylF9-PM-MphtPmjWtTYmmiSHfuS3t0aXYVB0EM42JuLSsLLLA";
membrane.export(exportCapability,
    {
        uri: "https://example.com",
        allowQuery: true,
        method: "get",
        headers:
        {
            "X-My-Header": "My_Header_Here"
        }
    },
    (error, resp) =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
        else
        {
            console.log(resp); // successful response
        }
        /*
        response =
        {
            capability: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-AQBJT_0r4O1Um6Xhe5F3T228Y_Tza2REq8etjMcRhQHemamQuVX4kIRdZHwhVa75SrPFri8Go_80BWmWM9xuHA"
        }
        */
    }
);

Alternatively, re-exports an already existing capability through the membrane. For example:

const exportCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-E0dTSQY_Tq01tZtMAfQANR97S3jB8QXrDDv5dylF9-PM-MphtPmjWtTYmmiSHfuS3t0aXYVB0EM42JuLSsLLLA";
membrane.export(exportCapability,
    {
        capability: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-LI1kp6Wwf0WxkAL3x6E5Zmoy3ktmLd5oit9BnDIGTsx2OqkVoCTwfO9SvS9loWaV7HLwc6lXi4CNq7Hzjpajow"
    },
    (error, resp) =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
        else
        {
            console.log(resp); // successful response
        }
        /*
        response =
        {
            capability: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-o0JX1SclvWshklZlxyPeX8Z3kgwlKpqBOMvoolbg-wKeUVwNz6VD-2kETJz5pTZRW8krzEXEYdmzvWYH06fDFA"
        }
        */
    }
);

membrane.query(queryCapability, query, callback)

  • queryCapability: Capability URI Capability to query membranes.
  • query: Object (Default: {}) Query to execute.
    • id: String (Default: undefined) Id of the membrane to query.
    • lastId: String (Default: undefined) Id of the last membrane from previous query, used to return more results if there are more results to retrieve.
    • limit: Number (Default: 1) Limit on the number of results. The number of results will be less than or equal to the limit.
  • callback: Function (error, response) => {}
    • error: Error Error, if any.
    • response: Object Response object.
      • membranes: Array An array of membranes ordered by 'id'. Each result contains id and capabilities corresponding to the membrane.
      • completed: Boolean true if no more results, false otherwise.

Queries for existing membranes. For example:

const queryCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-egK2BKhEO9cNISYbfw0Kngpd-7jXp6eqJC98rxaOlDME0Sa6HWfJu5FzbITemg7GNlZY5-e6DW-DbElrs9IcvQ";
membrane.query(queryCapability, null, (error, resp) =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
        else
        {
            console.log(resp); // successful response
        }
        /*
        response =
        {
            membranes:
            [
                {
                    id: "my-first-membrane",
                    capabilities:
                    {
                        export: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-E0dTSQY_Tq01tZtMAfQANR97S3jB8QXrDDv5dylF9-PM-MphtPmjWtTYmmiSHfuS3t0aXYVB0EM42JuLSsLLLA"
                        revoke: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-1lCiUqEOUpQwe6XKWM8unsu4667NyS7kNYSIKCw6pEm2-zRnwDmdoJkarbN81_Bo_cwWnfuXR4_2LhvInpNCYw"
                    }
                }
            ],
            completed: true
        }
        */
    }
);

membrane.revoke(revokeCapability, callback)

  • revokeCapability: Capability URI Capability to revoke a membrane.
  • callback: Function (error) => {}
    • error: Error Error, if any.

Revokes membrane. Revoking will delete all of the capabilities that were previously exported through the membrane. This call is asynchronous. This means that when the response is returned, the process of revoking the membrane may not yet be complete. It is safe to call revoke multiple times (for example, in case of an error response).

Example:

const revokeCapability = "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-1lCiUqEOUpQwe6XKWM8unsu4667NyS7kNYSIKCw6pEm2-zRnwDmdoJkarbN81_Bo_cwWnfuXR4_2LhvInpNCYw";
membrane.revoke(revokeCapability, error =>
    {
        if (error)
        {
            console.log(error, error.stack); // an error occurred
        }
    }
);