Node's Pastoral Musicians

    github-api-signature
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    github-api-signature

    npm version CircleCI

    Node.js signature generator for GitHub API using a PGP key.

    Install

    $ npm i github-api-signature

    or

    $ yarn add github-api-signature

    API

    generateKeyPair

    This method returns a Promise containing two properties publicKey and privateKey which are both strings.

    It generates a public and private PGP keys pair that can be used to sign commits with GitHub API using a GitHub user's informations and a passphrase.

    The public key should be added to the user's settings. The private key is then used with the createSignature method to sign the commit with the committer informations extracted from the payload sent to the API.

    Usage
    import { generateKeyPair } from 'github-api-signature';
    
    const passphrase: string = 'my secret phrase';
    
    const user: UserInformations = {
        name: 'Dohn Joe',
        email: 'github@ghost.com'
    };
    
    // Optional number of bits for the generated RSA keys pair.
    // Defaults to the maximum value 4096.
    const rsaBits = 4096;
    const type: 'ecc' | 'rsa' = 'ecc';
    
    generateKeyPair(user, passphrase, rsaBits, type)
    .then((keyPair: KeyPair) => {
        // keyPair = {
        //     publicKey: '-----BEGIN PGP PUBLIC KEY BLOCK-----...',
        //     privateKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----...'
        // };
    
        // Add publicKey to Dohn Joe's GitHub account settings.
        // Use privateKey to create commits signatures for Dohn Joe's as committer.
    });
    Type definitions
    async function generateKeyPair(
        user: UserInformations,
        passphrase: string,
        type: 'ecc' | 'rsa' = 'ecc',
        rsaBits: number = 4096
    ): Promise<KeyPair>
    
    type UserInformations = {
        name: string,
        email: string
    };
    
    type KeyPair = {
        publicKey: string,
        privateKey: string
    };

    createSignature

    This method returns a Promise containing a string which is the PGP signature that should be used on the GitHub API to sign your commit with the committer informations.

    Use this method with the same payload that you would send to the GitHub API POST /repos/:owner/:repo/git/commits endpoint.

    It accepts either an already git-computed commit payload (see GitHub's example) which is the git content for a commit object, or a CommitPayload object.

    When using a CommitPayload object, the author argument is mandatory, as opposed to the optional argument for the API. This is necessary since we need to generate the commit message string with the same date argument as GitHub will do to verify the signature.

    The committer argument is still optional and will default to the author value if omitted.

    In the following example, the commit will be signed for Dohn Joe. Hence, privateKey should be generated using Dohn Joe's informations.

    Usage
    import { createSignature, commitToString } from 'github-api-signature';
    
    const privateKey: string = `-----BEGIN PGP PRIVATE KEY BLOCK-----
    
    // Private key content //
    -----END PGP PRIVATE KEY BLOCK-----`;
    
    const passphrase: string = 'my secret phrase';
    
    const commit: CommitPayload = {
        message: 'Commit message',
        tree: 'tree-sha',
        parents: ['parent-sha'],
        author: {
            name: 'John Doe',
            email: 'ghost@github.com',
            date: '2018-01-01T00:00:00.000Z'
        },
        // Optional committer informations
        // Defaults to <author>
        committer: {
            name: 'Dohn Joe',
            email: 'github@ghost.com',
            date: '2018-01-01T00:00:00.000Z'
        }
    };
    
    // Using a CommitPayload object
    createSignature(commit, privateKey, passphrase)
    .then((signature: string) => {
        // signature = `-----BEGIN PGP SIGNATURE-----
        //
        // // Signature content
        // -----END PGP SIGNATURE-----`;
    
        const apiPayload = {
            ...commit,
            signature
        };
    
        // Use signature with GitHub API
        // https://developer.github.com/v3/git/commits/#create-a-commit
        // POST /repos/:owner/:repo/git/commits
    });
    
    // Using a git-computed commit payload string
    // commitToString returns the same format as "git cat-file -p <commit-sha>"
    const commitStr = commitToString(commit);
    createSignature(commitStr, privateKey, passphrase)
    .then((signature: string) => {
        // ...
    });
    Type definitions
    async function createSignature(
        commit: CommitPayload | string,
        privateKey: string,
        passphrase: string
    ): Promise<string> {}
    
    type UserInformations = {
        name: string,
        email: string
    };
    
    type GitHubUser = UserInformations & {
        date: string
    };
    
    type CommitPayload = {
        message: string,
        tree: string,
        parents: string[],
        author: GitHubUser,
        committer?: GitHubUser
    };

    Install

    npm i github-api-signature

    DownloadsWeekly Downloads

    0

    Version

    2.0.1

    License

    Apache-2.0

    Unpacked Size

    123 kB

    Total Files

    37

    Last publish

    Collaborators

    • jpreynat